Asa Dotzler <[EMAIL PROTECTED]> wrote in message news:<[EMAIL PROTECTED]>... > Jayesh Sheth wrote: > > I was wondering what system Mozilla.org uses to write and maintain > > documentation. In what ways can people help out with documentation? > > Where is help needed most (with regards to documentation)? > mozilla.org uses CVS to write and maintain documentation. > <http://www.mozilla.org/README-cvs.html> _Not_ a trivial barrier; for good or ill is not immediately obvious. Like a lot of complex systems, after a few times through it's duck soup. But the initial learning curve is cliff-like.
> People can help out with documentation by finding existing documents > that need udating, polish or other clean-up or by writing new > documentation about an area of the project that appeals. This, I think, is key: given a really dead-simple annotation system, a lot of things would at least be commented on. (Make a guess how many times XUL MIME-type is mis-stated *not counting external articles and such* ... I'd guess at least twice.) Egregious errors left standing create a lethargic tradition ... those who are well and truly in the loop know better, and those who aren't wander through an antique exhibition shaking their heads in bewilderment. Tech_docs rule #1: blaming the user/reader seldom leads to improvement in performance, however justified it might seem. So _either_ readers can't be bothered to react at the sight of bad information, _or_ a sufficiently facile method hasn't arisen. I vote for the latter; annotation is still (I say still cuz I was talking annotation 15 years ago) _still_ not effective. see http://www.webdav.org/ Maybe something like a blog link? or a mailto: that doesn't aim at DH? > Most help is needed in documenting the Mozilla code itself. Oh, now you've got my attention! I may have mentionned this to ioesch already: when I was dragging a large avionics R&D project out of the ditch (How did you call it, Ian? Like "spray-painting a moving car"? *grin*) I implmented a "write once" system, where practically every word an engineer wrote as comment was treated as gospel, if only for the moment. Because it was operational in a sense it _was_ gospel ... "This is how ya thought it might be done? Kewl ... thanks ... _this_ is how it's being done right at the moment, so work with that." Then I migrated each of those adamantine factoids through the document set, slashing and hacking a path as I went, excising as necessary. In the mid-term, there was a whole lot less high-level documentation (big chunks deprecated and trashed) with islets of actuality. Then my crew (gawd bless secretaries!) patched it all together, backing and filling. The unanticipated consequence of this was that engineers, seeing their gems being set in larger docs, applied their already good writing skills even more conscienciously [sp?], writing with an appreciative awareness that their words were bubbling up through the doc set. Coders' comments _actually are_ foundational, because they're operational, so they need to be recognized as such, and then they can buttress more lofty structures. My point is this: asking contributers to help comment code ... boy, that doesn't sit easily with me. But, how about mining the code for the building blocks of documentation? That's fail-safe and potentially produces a knowledge base, e.g. XUL MIME is correct in current usage, no?. (This occurred to me while thinking about XUL1.0: do a survey of _how things are actually being done_ and start with that.) [...] > We can definitely use the help. Right now getting involved takes some > persistance since we don't have this area well (or at all) coordinated. Seems to me there's sort of a quantum effect at play here ... those who are drawn to this sort of thing linger and a willing to wheel-spin somewhat. Given enough bodies wheel-spinning in the same direction, there may be some movement. > If you write a doc or make edits to an existing doc, developer or user > (or web developer) post it here and cc: me and I'll help you to get it > published in the most appropriate forum. *see above, my comments re: ease of contribution* This thread might work like an informal tracking bug! > Thanks for taking the time to get more involved. > --Asa hfx_ben
