On Thu, 30 Jul 2009 20:49:54 -0400, Jessica McKellar <jessica.mckellar@gmail.com> wrote:
Hi everyone,
I would like to help Twisted by adding documentation or reviewing existing documentation. However, I don't see many (any?) unassigned tickets regarding documentation of specific items, and because I am quite new to Twisted this makes it hard for me to determine where you wish I would focus my attention.
Hi Jessica, First let me say hooray. :) Any attention you can direct at any of Twisted's documentation will be much appreciated. :) Don't worry about trying to find an unassigned ticket. We try to keep all tickets assigned to someone. That doesn't mean the person is actively working on resolving the ticket, just that at some point in time, someone felt like that assignee should have responsibility for it. You may want to comment on a ticket before starting to work on it, asking if anyone is really working on it, or if there is any work which has been started which you can pick up. However, for most tickets, you'll very likely find answers in the negative for both these questions.
Where should I focus my attention? Want to open some tickets for me to claim? Is adding to API docs more important than updating the examples and howtos?
Either API doc work or howto work will be appreciated. I find that the API docs are in better shape overall (except for a few dark corners), so I would probably recommend focusing on howtos (and perhaps examples). Here are a few tickets in particular which I think it would be worthwhile to resolve: http://twistedmatrix.com/trac/ticket/1136 http://twistedmatrix.com/trac/ticket/1627 http://twistedmatrix.com/trac/ticket/3784 http://twistedmatrix.com/trac/ticket/3835
It looks like to add to the API docs you just update the doc strings for functions and let someone let pydoctor do its magic later. Is that true? Is there a special Twisted pydoctor incant to see how they'd look on the web before doing any hasty patch-submitting?
Yep, that's right. There's just a little specialness involved in the pydoctor invocation. Here's a decent command line to use: pydoctor --quiet --make-html --system-class \ pydoctor.twistedmodel.TwistedSystem --add-package twisted where the final "twisted" is the path to the "twisted" directory beneath a Twisted checkout (ie, the path which has as a sibling the "doc" directory, the "README" file, etc). Make sure you have epydoc installed or pydoctor will give you unpleasant looking results with unparsed epytext strings in it. There are two other areas in which I think documentation work would yield a great benefit. First, in general editing for readability, coherency, and general ease of understandability of any of the existing documents. These are often rough first drafts which no one was interested in polishing, or rough first drafts which have had dozens of minor edits by multiple authors with little concern for the overall document flow. Second, in a comprehensive high-level overview of what documentation is missing, what documentation exists, and how it all fits together. The output of this would be recommendations about what new documentation to write, what old documentation to scrape, what documents could be merged, more closely linked, or otherwise made to cooperate to provide easier access to the information they present. This is probably a big task, and one which requires familiarity with a lot of Twisted. I'm not sure how much Twisted experience you already have, but I wanted to mention it in case it sounds like something you'd be interested in. Finally, a couple years ago an attempt was made to seriously do something about the state of the documentation. It didn't get far enough to produce actual changes to the documentation, but it did produce some output. This may be useful. You can find it on the wiki: http://twistedmatrix.com/trac/wiki/DocumentationAnalysis
I'd like to update http://twistedmatrix.com/trac/wiki/ContributingToTwistedLabs to include some of this information as well as help I got earlier for updating xhtml documentation.
That sounds like a great idea. Wiki pages require a special permission to be set on your trac user. If you let me know what your username is, I can take care of adding that for you. Thanks! Jean-Paul