[Twisted-Python] More on docs

Mary Gardiner mary-twisted at puzzling.org
Fri Oct 8 07:57:31 EDT 2004


Sorry, I appreciate that I spend more time ranting about getting help
writing docs than I do writing, but... again.

Unfortunately the fastest way for me to write docs is to take rough
drafts by someone else and edit them into a helpful style with examples
and whatnot. Writing docs from scratch is fairly slow because I have to
spend a lot of time with the code, far more than the developers would have
to spend. And usually anything I say about design designs or high level
rationale will subsequently need to be corrected.

So, it would be fastest *for me* if developers wrote scratch drafts and
I edited them and improved the examples etc. Which is great, but also
unlikely to happen.

I figure something that is more likely to happen is that developers will
be explaining something to someone and accidently generate drafts as
they go. For example: mailing list posts, IRC logs and blog entries. So,
if you see or participate in a good "using something" discussion,
particularly on IRC, please send me a copy and I'll do my best to
edit/re-write it into a usable piece of documentation.

As my part of the bargain, it really is time I went back through the
archives and mined them for good posts.

Ta,

Mary




More information about the Twisted-Python mailing list