[Twisted-Python] Questions about adding documentation

[Kevin Horn]

On Thu, Jul 30, 2009 at 10:35 PM, Jean-Paul Calderone <exarkun at divmod.com>wrote:

> On Thu, 30 Jul 2009 20:49:54 -0400, Jessica McKellar <
> jessica.mckellar at 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. :)
>
>
Let me second that Hooray!

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.


>
> >
> >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).
>

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.

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.

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"

"To make an IMAP server, write classes to implement the IAccount, IMailbox,
IMessage, and IMessagePart interfaces defined in twisted.mail.imap4"

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.
And Twisted is BIG.  It's hard to find things sometimes...

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.


> 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.
>

More true in some places than others, but a definite problem in some places.
A personal pet peeve of mine is the "What Deferreds don't do: make your code
asynchronous"
section of
http://twistedmatrix.com/projects/core/documentation/howto/gendefer.html

There's a nice big example of what Deferred's don't do.  OK, great, but if
I'm new to Twisted
and the async style of coding in general, then what *DO* I do to make my
code asynchronous?
(NOTE: some of this I think will be helped in the upcoming Deferred
documentation rewrite...see the
"Deferred documentation rewrite" thread on this list for the last day or
two)


> 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.
>

Emphasis on "how it fits together", IMHO.  Navigating Twisted's'
documentation (outside the API docs)
is a nightmare.  I often find myself just having to use Google searches.


> 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 looked at this a while back, but I found it pretty much incomprehensible.


>
> Thanks!
>
> Jean-Paul
>

A couple of other things:

There are several barriers to improving Twisted's docs
- you have to know a fair amount about Twisted to write about some parts of
it
- you have to know a lot about Twisted to write about Twisted from a high
level, big-picture sort of perspective
- you have to know some seriously deep Twisted magic to even speak
intelligibly about certain things
- once you know enough about Twisted to really explain it...it seems you are
no longer able to explain it :)

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?

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.

Also:
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 + ...).

Anyway, I hope my rambling is helpful...

Kevin Horn
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://twistedmatrix.com/pipermail/twisted-python/attachments/20090731/4fc7d3f6/attachment.htm