[Twisted-Python] Task-based documentation started

[Kevin Horn]

On Tue, Feb 1, 2011 at 4:15 PM, Glyph Lefkowitz <glyph at twistedmatrix.com>wrote:

>
> OK.  For what it's worth I share your desire for a new / better term but I
> can't think of one.
>
>
Recipes?  Snippets?  Tidbits?  Morsels?  Quickies? "How do I..."s?  Quick
Examples?  Simple Examples?  Examples?  Blurbs?

A lot of the various example scripts actually fulfill this function, though
if you don't know about them, you're out of luck.  And they have no
explanatory text to go along with them.

Some of the questions in the FAQ fulfill a similar purpose, I think, and
would benefit from a simple example to link to.

I'd like to see a bajillion of these, but only if we have a way to test the
sample code.  Otherwise it's a maintenance nightmare.  (Note that when stuff
changes and the example code breaks, it's also a flag to update whatever
docs point to it, so the idea of testing sample code isn't just to help the
code, but also the narrative docs that go along with it.)

----

I agree with Glyph that "templates" to guide docs authors would be an
excellent tool to have.

----

As far as Jacob KM's documentation series, I also think it's pretty good, so
let's compare Twisted's docs to what he suggests to write:

   - step-by-step tutorials,

Twisted has precisely one of these (the finger tutorial).  A lot of people
hate it.  It should be fixed or replaced, and we should also have more of
these.  You could probably also count web-in-60 as one of these, too I
guess, so maybe we have 2.

   - overviews and topical guides to the various conceptual areas of your
   project, and

Pretty much anything in the various "howto" directories, though in the docs
themselves they tend to be called "Developer Guides" (which I think is a
better name).  We have a lot of these, they just need to be better
organized/edited, and a bit more coherent.  Some are fantastic.  Some are
stubs.  Some are out of date.  Some are flat wrong.

   - low-level, deep-dive reference material.

The API docs.  Which are great in some places, dismal in others.  There
needs to be a systematic review of this to figure out what's missing.  A
"template" for docstrings wouldn't be a bad tool to have either.

Kevin Horn
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://twistedmatrix.com/pipermail/twisted-python/attachments/20110201/31d8076b/attachment.htm