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

Mary Gardiner mary-twisted at puzzling.org
Tue Jan 17 06:57:53 EST 2006


Unfortunately, the sprint involved less people than I'd hoped. I'd like
to thank Andrew Bennetts and David Blewett for their documentation
revies at
http://twistedmatrix.com:8080/twisted/wiki/DocumentationAnalysis/DocumentList
though, and Chris Armstrong and Jean-Paul Calderone for being around to
help out people who showed up. And also anyone who poked their head in
while I was out.

Where to from here?

Well, first of all I still think the idea of documentation reviews is a
reasonably good way to improve the documentation, because it forces
people to think about who the intended audience of the document is and
what the purpose of the document will be. This is surprisingly hard to
do when you just sit down and write something -- really! Also, Andrew
assures me that writing an expert review is easier than writing a
document.

So while I know that only a small percentage of users have the time or
inclination to be project contributors, I'd like to encourage anyone who
finds an eager but disappointed documentation user to go through the
process of
http://twistedmatrix.com:8080/twisted/wiki/DocumentationAnalysis/DocumentList
I intend this to be an ongoing project.

At some point I will also do a template for 'reviewing' non-existant
documents -- David's valiant review of non-existant documentation shows
that I could improve the template for this task.

Next up will be another sprint in a month or two to *act* on the
reviews. I am hoping that improving a document based on a review will be
far easier than improving it based on scattered one-shot bug reports or
our gut instincts. Dates and times soon.

Further discussion of documentation improvement ideas welcome on
twisted-python at twistedmatrix.com

-Mary

-- 
<ilikewine> that mp3 sounds like that band is from williamsburg
<ilikewine> its an awful place
<ilikewine> where everybody wears stripes




More information about the Twisted-Python mailing list