[email protected] wrote: > It's there, but it's scattered and incomplete, as everything else. > One of us will have to start this effort, but there is no way that core > devs alone will be able to put the bulk of the documentation together. > We can, for example, start with the Table of Contents, write the > introductory parts, but then some volunteers will have to step up and > start figuring out what to write in there. Speaking for myself, I have > no time for both coding/testing and heavy-duty documentation. It's not > that I don't think documentation is not important -- it is -- it's just > lack of time. Writing good documentation takes as much time as writing > code. If someone here really wants to help the project, doesn't code but > writes English well... consider volunteering as a documenter! -- it's > fun, you get to try OpenSim in all sorts of modes, so that you know how > it works and what to write, and you also get to pick on core devs' > brains. I know for a fact that many of you here are already advanced > enough in OpenSim configuration and testing that you could do this very > effectively... > > Anyway, if I had a say in it, my preference would be to do the bulk of > the documentation effort between 0.7 and 1.0. After 0.7 gets tagged, and > if no one beats me to it, I'll do a draft of the TOC, and then ppl will > have a better idea of what's needed.
I think a TOC will help but it's probably not enough. I think people will need more of an outline if this approach is going to work. It could be pretty minimal but it needs to be enough to give people a fighting chance. We've already seen the result of the minimalist, unstructured approach in the wiki. And to be honest, I feel that not explaining code is already creating a situation where only people with buckets of time or a high level of experience will attempt to interact with OpenSim on the code level. Writing good documentation is just as much a part of a good programmer's role as writing the code itself. > > (FYI, here are the pieces currently about ROBUST, but this needs to be > revised, anyway. > http://opensimulator.org/wiki/OpenSim_Services_and_Service_Connectors > http://opensimulator.org/wiki/ROBUST > ) > > > Fly Man wrote: >> Diva, >> >> That was a discussion that has been done on the #opensim-dev channel and >> so far, I haven't seen a single documentation point entrusted to the >> Wiki about the new ROBUST components >> >> Maybe it's a good idea for you to lead the way ? >> >> 2010/1/8 <[email protected] <mailto:[email protected]>> >> >> Impalah Shenzhou wrote: >> >> > There is only one thing I really miss for making this: the interfaces >> > between simultator->UGAIM are not clearly documented and we have to >> > navigate into code to konow what we have to do. >> >> I have pointed to the code, because that's all there is at the moment, >> and it's not even finished. That is not to say that that's all there >> ever will be. Documentation is in the near future, at least for me, as >> something that will be increasingly important for the project, critical >> even. I'm not sure core devs can do it alone, though -- in fact, I'm >> pretty sure we can't. I think we need to organize this community of >> users-developers much better than we have been doing before to produce >> "The OpenSim Guide." It can't be a free-for-all, anarchic, design-free >> wiki like we have been having so far (this is my opinion only, and >> doesn't represent any official position of the core devs, but I'm >> sticking to it). We need leaders (i.e. "Wikipedia admins"). Personally I >> would love to see the emergence of a group of people here who would >> become the "core documenters". Those people would work very closely with >> core devs in order to "extract" the knowledge out of our heads and into >> documentation. >> _______________________________________________ >> Opensim-dev mailing list >> [email protected] <mailto:[email protected]> >> https://lists.berlios.de/mailman/listinfo/opensim-dev >> >> > _______________________________________________ > Opensim-dev mailing list > [email protected] > https://lists.berlios.de/mailman/listinfo/opensim-dev > -- Justin Clark-Casey (justincc) http://justincc.org http://twitter.com/justincc _______________________________________________ Opensim-dev mailing list [email protected] https://lists.berlios.de/mailman/listinfo/opensim-dev
