On Fri, Jul 31, 2009 at 11:10 PM, Steve Steiner (listsin) < listsin@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 ;-).