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

Moof moof at metamoof.net
Tue Jan 17 07:30:28 EST 2006


[Removed twisted-web from To: list]

On 1/17/06, Mary Gardiner <mary-twisted at puzzling.org> wrote:
>
> Unfortunately, the sprint involved less people than I'd hoped.


I'm sorry I couldn't join in. The Real World interefered with me at the last
minute and left me mostly offline durign the weekend, or I would have dived
in considerably. I'll try and have a read through the wiki this week and see
if I can add any contributions.

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.


How about adding a links to "Don't like this document? Can't work it out
what you need to know? Review it" liberally throughout the documentation. It
may encourage people to keep critiquing, and thus help improve it.

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.


How about adding links in strategic places to "Request Documentation". I
don't know if you'd want to integrate this with the twisted roundup somehow.

In fact, a document on "what to do if you can't find the documentation you
want" might be helpful, and possibly stop the complaints about lack of
documentation. Include things like where to find the IRC Channel, how the
bug system works, and so on.

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.

Moof
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://twistedmatrix.com/pipermail/twisted-python/attachments/20060117/2b7d7542/attachment.htm 


More information about the Twisted-Python mailing list