[Twisted-Python] Questions about adding documentation

[Steve Steiner (listsin)]

On Jul 31, 2009, at 4:23 PM, Glyph Lefkowitz wrote:
...
> I certainly wouldn't mind switching to a tool that has lots of fancy  
> features that lore lacks, but a hit-and-run approach where we just  
> switch tools in the hopes that it will make something better may  
> leave us in a worse situation than we already are.

I'm wondering if there's an inventory of the various types of  
documentation systems currently in use.

Not just "systems" but mostly "stray documentation."

 From this discussion, it doesn't seem that the Lore formatted and  
built docs are as much of a problem as the fragmentation into  
tracwiki, main docs, mailing list, etc. that we've discovered as we've  
been discussing it.

Since "everything" is not in the build system anyway, perhaps starting  
a branch, in a new build system (Sphinx), where we pull things in, one  
chunk at a time, will not be a hit and run approach, but will force  
the reorganization of the docs into one, actually unified format.

Presentation is another issue, for another day.

Then we can all see what's documented, what's not, what's old and out  
of date, etc.

With a dating system as discussed elsewhere, the docs will actually  
improve over time instead of becoming more fractured and out of date  
with no traceability.

Just my 13.4 cents.

S