[Twisted-Python] Questions about adding documentation

[Glyph Lefkowitz]

On Fri, Jul 31, 2009 at 11:10 PM, Steve Steiner (listsin) <
listsin at integrateddevcorp.com> wrote:

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

"This time for sure, Rocky!"

If you actually want to volunteer to do all of the work for this (which I
outlined in my previous message) then feel free.  But attempts to fix the
world by blowing it up are rarely successful.  A better approach would be to
incrementally enumerate the things which have been covered on the mailing
list and wiki, then pull them into the lore docs one at a time.

Of course, the people who have actually volunteered their time, rather than
their suggestions, seem to agree with this general outline :).

Something you have to keep in mind with grand efforts like "let's rewrite
all the docs in the hottest new ReFrumpledText format" is that Twisted is a
product mostly of people's spare time, and therefore the person working on
it may suddenly become busy and lose interest.  When they *do* lose interest
— possibly for a year or longer — we need to make sure that things are in a
good state in the meanwhile, and their efforts have improved things.  Each
small improvement to the lore documentation will improve the overall
documentation situation.

As you put it, a big problem here is:

the fragmentation into tracwiki, main docs, mailing list, etc
>

if the fragmentation is instead into tracwiki, main docs, sphinx docs,
mailing list, etc, the problem has actually gotten *worse*, not better.
Especially if the sphinx person walks away halfway through the effort, and
then some other person comes along and says, "oh hey, what we should *really
* do is rewrite all the docs in YAML", then rewrites another small subset of
them and leaves.

I hope you can see why I want to hold on to our current toolchain until we
have someone around who has demonstrated a much deeper commitment to
documentation than anyone yet has.  For example, Steve, if you close 100
existing documentation tickets in the next week, then make the exact same
suggestion again, I'll be a lot less resistant ;-).
-------------- next part --------------
An HTML attachment was scrubbed...
URL: </pipermail/twisted-python/attachments/20090731/02ef6e87/attachment.html>