We should have organize a wiki to allow people
to work in a bazaar style.
zwiki (on zope) is one of the best wikis
I've ever seen. Why not base our doc system
on it. This will allow users to contrubute,
change, revise, moderate docs easily and
more importantly you will make any web site
visitor a "potential contributer" to documentation.
With some extra effort you can still
generate "cathedral" documents out of them.
Beside these you can control who will modify docs
by the "user control mechanism" of zope.
Imran
Alex Vincent wrote:
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
I dearly hope you're not suggesting I'm trying to run a cathedral... ;)
(although I am a fervent believer in Catholicism)
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)
We're in pretty damn good shape, compared to six months ago. Is it good
enough? Hell no, and we all realize that. We're getting there. Good
people, good volunteers that want to help us are falling through the
cracks, and we realize that too.
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
