<div class="gmail_quote">On Thu, Jul 30, 2009 at 10:35 PM, Jean-Paul Calderone <span dir="ltr"><<a href="mailto:exarkun@divmod.com">exarkun@divmod.com</a>></span> wrote:<br><blockquote class="gmail_quote" style="border-left: 1px solid rgb(204, 204, 204); margin: 0pt 0pt 0pt 0.8ex; padding-left: 1ex;">
<div class="im">On Thu, 30 Jul 2009 20:49:54 -0400, Jessica McKellar <<a href="mailto:jessica.mckellar@gmail.com">jessica.mckellar@gmail.com</a>> wrote:<br>
>Hi everyone,<br>
><br>
>I would like to help Twisted by adding documentation or reviewing existing<br>
>documentation. However, I don't see many (any?) unassigned tickets regarding<br>
>documentation of specific items, and because I am quite new to Twisted this<br>
>makes it hard for me to determine where you wish I would focus my attention.<br>
<br>
</div>Hi Jessica,<br>
<br>
First let me say hooray. :) Any attention you can direct at any of Twisted's<br>
documentation will be much appreciated. :)<br>
<br>
<div class="im"></div></blockquote><div><br>Let me second that Hooray!<br><br>I thought I would jump in here with sort of an outsiders perspective on what I think needs to happen with the Twisted docs. Even though I've been using Twisted for a couple of years, I'm still new enough at it that I remember what my frustrations were (and sometimes still are) with the docs. This is all just my opinion, though...I don't mean to ruffle anyone's feathers.<br>
<br></div><blockquote class="gmail_quote" style="border-left: 1px solid rgb(204, 204, 204); margin: 0pt 0pt 0pt 0.8ex; padding-left: 1ex;"><div class="im"><br>
><br>
>Where should I focus my attention? Want to open some tickets for me to<br>
>claim? Is adding to API docs more important than updating the examples and<br>
>howtos?<br>
<br>
</div>Either API doc work or howto work will be appreciated. I find that the API<br>
docs are in better shape overall (except for a few dark corners), so I would<br>
probably recommend focusing on howtos (and perhaps examples).<br>
</blockquote><div><br>I agree. The API docs need some work (there are a LOT of undocumented methods), but overall I think they are in much better shape than the rest.<br><br>Howtos and examples would be fantastic, as well as clean up of some of the existing stuff (as Jean-Paul notes below). Browsing through the source code for long enough should give most coders the idea that all the pieces are there to build, e.g. an IMAP server, and those pieces ARE there, but it takes a lots of reading of lots of stuff in lots of different places (text docs, API docs, cred docs, application docs, etc., etc.) to figure out which pieces you need and how to put them together.<br>
<br>I picked an IMAP server as an example, because of the AHA! moment I had when I read the following in the in the Abe Fettig O'Reilly book"<br><br>"To make an IMAP server, write classes to implement the IAccount, IMailbox, IMessage, and IMessagePart interfaces defined in twisted.mail.imap4"<br>
<br>The next two sentences complete the description of the process, but the key point is that for most parts of Twisted, there isn't much that tells you how all of the various parts fit together.<br>And Twisted is BIG. It's hard to find things sometimes... <br>
<br>Some of this could be improved by expounding on the API docs for these interfaces, but I think a broad overview for many of these areas would help immensely.<br> </div><blockquote class="gmail_quote" style="border-left: 1px solid rgb(204, 204, 204); margin: 0pt 0pt 0pt 0.8ex; padding-left: 1ex;">
There are two other areas in which I think documentation work would yield a<br>
great benefit. First, in general editing for readability, coherency, and<br>
general ease of understandability of any of the existing documents. These<br>
are often rough first drafts which no one was interested in polishing, or<br>
rough first drafts which have had dozens of minor edits by multiple authors<br>
with little concern for the overall document flow.<br>
</blockquote><div><br>More true in some places than others, but a definite problem in some places.<br>A personal pet peeve of mine is the "What Deferreds don't do: make your code asynchronous"<br>section of <a href="http://twistedmatrix.com/projects/core/documentation/howto/gendefer.html">http://twistedmatrix.com/projects/core/documentation/howto/gendefer.html</a><br>
<br>There's a nice big example of what Deferred's don't do. OK, great, but if I'm new to Twisted<br>and the async style of coding in general, then what *DO* I do to make my code asynchronous?<br>(NOTE: some of this I think will be helped in the upcoming Deferred documentation rewrite...see the <br>
"Deferred documentation rewrite" thread on this list for the last day or two)<br></div><div> </div><blockquote class="gmail_quote" style="border-left: 1px solid rgb(204, 204, 204); margin: 0pt 0pt 0pt 0.8ex; padding-left: 1ex;">
Second, in a comprehensive high-level overview of what documentation is<br>
missing, what documentation exists, and how it all fits together. The<br>
output of this would be recommendations about what new documentation to<br>
write, what old documentation to scrape, what documents could be merged,<br>
more closely linked, or otherwise made to cooperate to provide easier<br>
access to the information they present. This is probably a big task, and<br>
one which requires familiarity with a lot of Twisted. I'm not sure how<br>
much Twisted experience you already have, but I wanted to mention it in<br>
case it sounds like something you'd be interested in.<br>
</blockquote><div><br>Emphasis on "how it fits together", IMHO. Navigating Twisted's' documentation (outside the API docs)<br>is a nightmare. I often find myself just having to use Google searches.<br>
</div><blockquote class="gmail_quote" style="border-left: 1px solid rgb(204, 204, 204); margin: 0pt 0pt 0pt 0.8ex; padding-left: 1ex;">
Finally, a couple years ago an attempt was made to seriously do something<br>
about the state of the documentation. It didn't get far enough to produce<br>
actual changes to the documentation, but it did produce some output. This<br>
may be useful. You can find it on the wiki:<br>
<br>
<a href="http://twistedmatrix.com/trac/wiki/DocumentationAnalysis" target="_blank">http://twistedmatrix.com/trac/wiki/DocumentationAnalysis</a><br>
<div class="im"></div></blockquote><div><br>I looked at this a while back, but I found it pretty much incomprehensible.<br> </div><blockquote class="gmail_quote" style="border-left: 1px solid rgb(204, 204, 204); margin: 0pt 0pt 0pt 0.8ex; padding-left: 1ex;">
<br>
Thanks!<br>
<br>
Jean-Paul<br>
</blockquote></div><br>A couple of other things:<br><br>There are several barriers to improving Twisted's docs<br>- you have to know a fair amount about Twisted to write about some parts of it<br>- you have to know a lot about Twisted to write about Twisted from a high level, big-picture sort of perspective<br>
- you have to know some seriously deep Twisted magic to even speak intelligibly about certain things<br>- once you know enough about Twisted to really explain it...it seems you are no longer able to explain it :)<br><br>Not trying to offend...everyone in the Twisted community I've talked to has been very helpful, but sometimes when you know a complex topic really well, it becomes difficult to explain things in such a way that someone new to that topic will understand. Does this make sense?<br>
<br>Sometimes I think what is needed is someone who knows basically nothing about Twisted to go about learning it...and then writing down how they did it.<br><br>Also: <br>Some (more) documentation about how to write docs for Twisted would really help people who are willing (and in some cases eager!) to contribute, but feel the barrier to entry is too high (they don't want to figure out pydoctor + epydoc + xml processing + ...).<br>
<br>Anyway, I hope my rambling is helpful...<br><br>Kevin Horn<br>