[Twisted-Python] Questions about adding documentation
Steve Steiner (listsin)
listsin at integrateddevcorp.com
Fri Jul 31 23:10:37 EDT 2009
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.
More information about the Twisted-Python