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