Re: XPCOM Documentation tree

Daniel Wang wrote:
> Alec Flett wrote:
> 
>> I got tired of all the meta-discussion about documentation
> 
> 
> that's probably because newsgroup is a good place for such discussion 
> and Bugzilla is a better place for discussing specifics of a doc?
> 

Not its because we have the classic "too many chiefs" problem - everyone 
wants to declare that docs should be written this way or that way or 
should live here or there and nobody wants to actually write docs.

I am absolutely flabergasted that the response to actual documentation 
has been "please don't check this in without following some idioic guide 
that hasn't been written yet"

> 
> why not http://www.mozilla.org/catalog/architecture/xpcom/ ?

because I'm actually writing the docs. When you write them, you can put 
them there.

> documentation and project-specific information should be kept separate

Whatever.

> 
> And please open a bug for tracking this

No. I'm writing docs not filing bugs. File them yourself.

>> here's where I need your help:
>> - [snip]
>> - nsIPref* (daniel?)

HElloo... nsIPref is not part of XPCOM.
> 
> 
> fantasai is working on a new style guide

wake me when its over. Kudos for Fantasai for actually writing it though.

> 
>> [snip]
>> - I want to write my docs in TeX
> 
> 
> Please use HTML or plain/text:

Oh god... lighten up. That was a joke.

> 
> README-cvs.html is obsolete. Use 
> http://www.mozilla.org/catalog/development/website/cvs-website.html

So the doc with correct instructions is obsolete and the doc with all 
the typos that makes no sense is the one we should use? Good luck with that.

> I think you are missing the motives behind all the meta-d11n efforts. It's very difficult to become a contributor in documentation (or QA, or Mozilla development). A lot of people have announced their intent to help, but guess what? Most got no assistance from any human being or meta-document. Is there any wonder why nobody is writing documentation and people are trying to fix this?

The fact is a lot of people have offered meta-help - help organizing 
documents, help telling other people how to write their documents, but 
very, VERY few people have actually sat down and written anything. The 
problem is not some meta document or someone holding someone else's 
hand. The problem is nobody is writing docs. A style guide or a 
documentation plan is not going to solve that.

Look, I'm sick of all this process with respect to documentation. You 
guys need to just get over yourselves and pitch in with actual work. I 
see twenty people working in a bubble trying to direct people who 
actually produce things, to produce them by THEIR rules which don't even 
exist. When I see you've demonstrated some reasonable expertise in this 
area, I'll listen, but until then either get your hands dirty or quiet down.

I'm going to write a "how to write documentation" doc this week. It will 
be a sort of mozilla-specific "how to be a tech writer"

Alec