[Twisted-Python] Documentation virtual sprint, TODAY, Sat 14th January

Mary Gardiner mary-twisted at puzzling.org
Tue Jan 17 15:51:23 EST 2006


On Tue, Jan 17, 2006, Moof wrote:
> On another note, a wealth of explanations, normally for small areas of
> twisted, are given out on the IRC channel and the mailing lists. Maybe
> making it easy to post snippets from IRC that are searchable might be
> a good idea to make "pseudo-documentation". Ditto a way of referring
> to particular threads on the main mailing lists. For example, I've
> seen several threads on IRC and on the mailing lists about how the
> twisted logging system works in much more detail than the
> documentation on the site. Making it easy to link to the various
> discussions we've had might be a big help to first-time readers of the
> docs.

My immediate reaction to this was to worry about maintainability in that
these conversations, just like our docs, will likely eventually stop
being "the right way" to do things.

Repeated experience has shown that we've got very few people (at a
guess, somewhere between 2 and 5 people, comprising about 0.05% in total
of a fulltime worker by time expenditure) who are worried enough about
maintaining the docs to actually do anything about it (and some more who
are willing to point out problems). This kind of thing is hard for
editors to work with -- they have to read through a whole conversation
to find out if any bit of it is out of date, and if so, they're
essentially forced to either turn it into a document or nuke the whole
thing.

Essentially what I'm trying to do here is find a balance between:

 - having lots of up-to-date documentation, even if it's not in a hugely
   friendly form (IRC conversations, for linguistic and social reasons,
   are low bandwidth even when there's meat to the discussion), which is
   a good thing

 - having lots of documentation in an incredible array of hard-to-edit
   forms which is constantly mostly out-of-date, which is a bad thing

For various reasons, mostly idiosyncratic, I tend to be biased towards
having a smaller set of well-maintained well-edited documentation than a
larger set of poorly maintained randomed documentation. But what are
other people's experiences with projects that have particularly good or
particularly bad documentation?

-Mary




More information about the Twisted-Python mailing list