Re: weblog post: organizing the documentation effort

fantasai wrote:
> http://fantasai.inkedblade.net/weblog/2004/documenting/
> 
Some comments...

I'm fairly new to Mozilla, and I find it difficult for two reasons:  1) 
the overall complexity of everything, and 2) incomplete and imprecise 
documentation.

A well-organized DevMo could help 1).  One way would be to start from 
the top of the Mozilla universe and work down.  At each level, answer 
all the questions that readers might ask, like:  What exists?  Where can 
I find it?  What is it for?  What does it really do in Mozilla?  What 
tools are used to create it?  What Mozilla-specific usage of the tools 
applies?  What standards does it comply with?  What Mozilla-specific 
exceptions to the standards are there?  What does it contain?

Essentially, the Mozilla universe seems to contain two big piles of 
code, Mozilla and mozdev, with corresponding piles of bugs.  Each pile 
of code contains files, which have various types and are grouped in 
various ways.  This gives structure to that "one giant emptiness" that 
you mention.  If you dig down through the piles and answer my nine 
questions for everything you find, then you have finished the job.

A more "open-source" approach to documentation could help 2).  You touch 
on this right at the end.  It's not "slightly off topic".  It's 
absolutely central.  The documentation will never be complete and 
accurate.  Ultimately, if you want to know something and you can't find 
it documented, you can go and read the source code and find out for 
yourself, and/or go to the community to ask.  But the documentation 
rarely makes this clear.  It's mostly written as if for a commercial 
product where source and community are not available.

Regarding bugs, you seem to want to make things more complex.  I think 
that might be counter-productive, as complexity itself is a barrier to 
getting things fixed.

I suspect Mike's assertions #3 (that the gap between NEW and ASSIGNED is 
too big), and #4 (that finding bugs for skills is a barrier) are not 
helpful.  It seems to me that when you tackle a bug you can never be 
quite sure where the work will lead.  That is why the gap is big, and 
why you can't tell in advance what skills will be needed.

It would help me to understand the arguments if you could give actual 
examples of bugs that you think illustrate them.

-- 
Rod Whiteley