[Opensim-dev] User services refactoring status

[Cristina Videira Lopes]

On Jan 8, 2010, at 1:46 PM, Justin Clark-Casey wrote:
> Writing good documentation is just as much a part of a good  
> programmer's role as writing the code
> itself.

Documentation is superlinear with the code.

Good documentation is not just a collection of disconnected articles  
covering the different parts of the system -- i.e. bottom-up. That's  
what happened so far, and the results show. Good documentation  
requires a top-down approach, i.e. someone needs to think about the  
TOC, set the tone for the document (extremely important!), and make  
sure language is consistent all over the place. Then the different  
parts can be filled up. Without this planning and continuous  
supervision of the document, the independent documentation efforts of  
the parts are bound to be a disaster as a whole, and highly  
ineffective in isolation (because nothing is ever isolated).

(Academic interjection: that's one of the main reasons why  
documentation is at odds with early-stage development that follows  
agile practices, especially in projects where there is no single point  
of control. One is top-down, the other is bottom-up.)

There's no question that the only people who can write the TOC, and  
set the tone, are the core devs plus 4 or 5 other people who are very  
familiar with OpenSim. But I think that there is a larger number of  
people who can fill in the parts -- as we can see from the wiki --  
except that we haven't been guiding them well, because... we haven't  
been guiding anything so far, things were too much in flux. I think  
we're reaching a point where this kind of coordinated effort can occur.