I dearly hope you're not suggesting I'm trying to run a cathedral... ;) (although I am a fervent believer in Catholicism)Is it the system that doesn't work or just the lack of documentation? No matter how many people we have who want to organize the writing of documentation, we still need people who are able and willing to write it. If there aren't people who are able and willing even to tell you what documentation needs to be written, how do you expect to find people knowledgable enough to actually write the documentation? (Perhaps the people in question would rather just write the documentation when they have time rather than putting their ideas on a centrally planned list?)Perhaps we'd be better off with a bazaar rather than a cathedral? Maybe we should have a sort of a "suggestion box" for suggestions for documentation that people would like to read. Then there would be room for documentation organizers who could forward such suggestions to the people who would be able to write the documentation. The organizers could also encourage (and annoy, etc.) the potential writers (such as module owners) to write documentation (with the amount of encouragement or annoyance proportional to the number of requests). -David
As far as I know, we do have a bazaar. Only problem is nobody's actually monitoring it, making sure the bazaar serves the customers. Right now it's more like a riot than a bazaar: everybody's mad, and few are trying to get anything really done.
Present company being that few. We're the policemen, the management, the vendors (pun not intended), the ones who are at least trying to make sure something productive happens.
I'm working on the baseline stuff when I can. I have fantasai's notes on my Writing Docs article, and I'll be revising it and the Roadmap/Manifesto/thingamajig when I get a chance. At this point, I am thinking moz.zope.org is primarily good for us as a document repository and little else. (Yes, I like all the good stuff ZOPE does for us, too -- but try convincing mozilla.org staff and the server farm team to start giving us some of ZOPE's features. We got bogged down there, and we're much better off focusing on our real goal of actually getting docs done and updated.)
I'm really of the opinion that we need the baseline stuff before we can start an organized push on docs -- and that we need only the baseline stuff. David's right -- bazaar has been proven to work better than cathedral, and documentation is simply a different product. But somewhere along the line, somebody must lay out the streets and give guidance on where to park your hot dog stands or roller coasters. You don't have to do it the way they tell you, believe me -- but if you don't have someone at least starting on those baseline things, you'll have hot dog stands in mud, underneath roller coasters. That's what we've got now. A very disorganized mess.
That's all I'm trying to get people to see: we need a core group of basic documents and guidelines, and a *minimal* set of absolute rules. How minimal? Style Guide (which isn't that hard), and a clarification on what checkin requirements we have (the review/sr draft -- which we keep telling everybody is a brick wall less than three inches in height).
I regret sounding frustrated right now, but the bottom line is this: Who's going to do this? Who's going to be in our documentation management group, the equivalent of the drivers group for the Mozilla browser, and create these guidelines? There's very damn few of us. In the last six months, there have been probably a dozen people at most actually creating new stuff for documenters to work with.
Look at the stuff I've put up on m.z.o in the last few months. The focus of all that is to help people understand how to do docs -- not force on them a particular way of doing it. Seriously, I just spent several hours last week crafting a suggested procedure on writing docs from scratch.
I think it's very important now to note we've got a solid baseline now at moz.zope.org: not perfect, not by a long shot... but instead of needing to write new documents on documentation, it's now a matter of editing and reviewing what we have created and posted. For instance, jkeiser's Gecko Document Map. If we could expand that to include subject matter experts (SRE's) and also create a larger map inspired by it for our full-blown docs effort, then we'll have something to point people to. My own work: yeah, some of it's out of date and a good deal of it is still in draft form, but we've got it now.
Here's what I said we needed (from the roadmap draft).
We need people for all of the following tasks:
* Cataloging documentation (got that)
o Searching the old documentation
o Filing links in the catalog for the documentation
o Determining what we have no categories for in our catalog, but we should have
o Determining relevant cross-links between categories (what category relates to another category)
* Verifying documentation is accurate (got that)
* Checking for spelling and grammar errors, and also consistent markup style in pages (got that)
* Editing out-of-date documentation (got that)
* Writing documentation where it's non-existent (search for it first!!) (got that last week)
* Writing documentation for beginners & intermediate people (I think this blends into our general Writing Docs bit, to an extent)
* Documenting Mozilla source code itself (as output by LXR) (I'm no longer as firm on this one as I once was -- particularly if we document DOxygen)
* Triaging Documentation bugs in Bugzilla (ok, we need an article on this)
* Creating CVS-compatible patches for check-in to mozilla.org or uploading them to moz.zope.org (we may do both, undecided yet) (guess what, Doctor does that for us, and I mentioned that in the Writing Docs article)
* Reviewing and super-reviewing documentation patches (that's Brian Heinrich's article on the r=/sr= process we've proposed)
This is taking us a long time. We know that. If there were more of us, and if we had more time available to commit to this effort, we'd probably be done by now and have a big push going as we speak. I've done what I can to rally people to the cause. I know there have been others interested, and others doing rallying too -- and I'm very thankful we've not attacked each other personally (only their work). Do I have all the answers? No. Do I act like I have all the answers? I hope not.
I'm just frustrated at everybody else's frustration and the perceived (and truthful) lack of support, I guess. Documentation is a serious problem, and we're not going to get it fixed overnight.
Let me get off my soapbox. The family has an old saying: "As long as you keep you're mouth shut, people only think you're an idiot. Once you open it, you remove all doubt." I know this missive is bound to irritate a few people, and I know I look like an idiot, but it had to be said.
Alex
