[Removed twisted-web from To: list]<br><br><div><span class="gmail_quote">On 1/17/06, <b class="gmail_sendername">Mary Gardiner</b> <<a href="mailto:mary-twisted@puzzling.org">mary-twisted@puzzling.org</a>> wrote:</span>
<blockquote class="gmail_quote" style="border-left: 1px solid rgb(204, 204, 204); margin: 0pt 0pt 0pt 0.8ex; padding-left: 1ex;">Unfortunately, the sprint involved less people than I'd hoped. </blockquote><div><br>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.
<br></div><br><blockquote class="gmail_quote" style="border-left: 1px solid rgb(204, 204, 204); margin: 0pt 0pt 0pt 0.8ex; padding-left: 1ex;">So while I know that only a small percentage of users have the time or<br>inclination to be project contributors, I'd like to encourage anyone who
<br>finds an eager but disappointed documentation user to go through the<br>process of<br><a href="http://twistedmatrix.com:8080/twisted/wiki/DocumentationAnalysis/DocumentList">http://twistedmatrix.com:8080/twisted/wiki/DocumentationAnalysis/DocumentList
</a><br>I intend this to be an ongoing project.</blockquote><div><br>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.
<br></div><br><blockquote class="gmail_quote" style="border-left: 1px solid rgb(204, 204, 204); margin: 0pt 0pt 0pt 0.8ex; padding-left: 1ex;">At some point I will also do a template for 'reviewing' non-existant<br>documents -- David's valiant review of non-existant documentation shows
<br>that I could improve the template for this task.</blockquote><div><br>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.
<br><br>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.
<br><br>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.
<br><br>Moof<br></div></div>