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. _______________________________________________ Opensim-dev mailing list [email protected] https://lists.berlios.de/mailman/listinfo/opensim-dev
