Chaotic and frustrating docs (Re: [Twisted-Python] "twisted.internet.app is deprecated"...)

Mary Gardiner mary-twisted at puzzling.org
Tue Jun 29 17:38:36 MDT 2004


On Thu, Jun 24, 2004, Henry James wrote:
> Needless to say, after an hour's fooling around in the doc (which is
> just as chaotic and frustrating as a year ago), I haven't found the
> "new way to doing things".

File bugs against it please, and assign them to me ("hypatia" is my bug
tracker username). The bugtracker is at http://twistedmatrix.com/bugs/

The ideal docs bug would go something like:

 I wanted to find information about [something]. I looked in [these
 docs] and didn't find the information I was looking for because:

  - there wasn't any information about [something]
  - information about [something] was confusing [somehow]
  - information about [something] was contradictory
  - information about [something] didn't address [some points]
  - information about [something] didn't seem relevant to [my use-case]
  - the [something] examples don't work
  - the [something] examples aren't clear [in some way]

As with all bugs, specific is better.

I'm happy to have people assign lots of small bugs to me (people always
feel the need to apologise for this after the third or fourth one). It
may seem weird filing six consecutive docs bugs, but it does let me do
the work in stages.

It's very hard to tell what needs to be changed without specific
examples -- documentation improvement is difficult because it's hard to
tell when it's reached some state of "sufficient goodness". In practice,
I've found specific bugs against the documentation inspire me to work on
that document, whereas the "docs suck!" feedback doesn't: too big a
problem.

> Suggestion to doc writers: If you change your "stancard way to doing
> things", please included a "code convertion guide" of some kind into
> your tutorial.

Please file bugs against documentation when this doesn't happen. In
practice I get assigned cleaning up, but I came to (non-web) Twisted
development fairly late and don't actually know the twisted.internet.app
boilerplate.

-Mary




More information about the Twisted-Python mailing list