Mitchell Baker wrote: > The key thing in a documentation effort is to get more good documents. > > To me, the entire issue of word usage (log-in vs login for example) is > very low on the list of things to care about. If someone writes a > document on how to use Mozilla components, when using XPCOM is > appropriate vs. when it's not, or how threading does or doesn't work in > Mozilla, we'll want it. If there's an easy way to make such a > document consistent with other docs, great. If not, we won't turn it > away because the author uses hyphens where others don't. Same with > spelling conventions. If British spellings appear in our docs because > the authors prefer those spellings, fine. I see no reason to irritate > people by decreeing tat their native usage is unacceptable. And > certainly not until we have a large set of documents and users are > actually complaining that the differences between spelling conventions > are a big problem with those existing documents. > > The key issue in a volunteer effort like the Mozilla project is to get > people to actually take the time to +write good documents+. I hope that > the energy reflected in these discussions will turn to this problem. > > > Mitchell >
This has been said before but here I go again: There are two main points to my critics against the current mozilla.org: difficulty of use, and the lack of structure. Here's why. Some time last year, I wrote a few documents about the DOM (both code doc and usage doc) (see http://mozilla.org/docs/dom). Everything was fine until I had to find a place to publish them. First I put it on a test account I had a on a free site. FTP and stuff, still good. Then I was asked to publish them on mozilla.org. Great I thought, that should be easy. Well nay. Leaving aside the new hardware and software (bigger hdd + linux cuz I couldn't use CVS on windows for whatever reason) I had to get, I had to apply for a CVS account, learn CVS, download the good module of the website through CVS (luckily I have the cable), and find a good location for my docs. This last point being so difficult that I ended up creating from scratch index pages for /docs/dom. Then came the time to maintain the pages. I had to keep my gila tree up to date and make sure that the site actually built (this is a website not mozilla) before checking in new files. The new doctor feature probably makes it a little easier, but nobody knows about it. I did all the above in my spare time and got little to no help (thanks Gerv though). My second point is that I have seen _at least_ 10 documentation writers (even professional ones) proposing their help in this very newsgroup. The only mozilla.org staff member who ever answered was Gerv. But he had nothing to answer, because there was no structure for the documentation. I do not see myself telling one of those writers with a full-time job "write a document about I-don't-know-what then do everything I did (see above) to publish your doc". The net gain from these 10-or-so writers was zero. This is the very reason why I work on moz.zope.org. dbaron will repeat that developers know cvs and that developers are those that should be writing documentation, but I think by now we have to admit that Mozilla developers do not write documentation. Either because the documentation structure sucks, or because they just don't want to. In the first case, moz.zope.org will make the structure much better and easier to use. In the second case, we will not turn off non-developers who want to write documentation just because cvs is so inaccessible for them. The conclusion is, even if we don't need strict style guides and spelling guides quite yet, a structure and a better framework are, imho, required in order to bring developers and contributors who will write documentation. It is naive to think that people will write documentation just because you ask them. I hope you see my point of view, -Fabian.
