On Fri, Jan 8, 2010 at 10:16 PM, <[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
I think this is definitely a start, and better than nothing. I know myself, the way I teach myself a code base sometimes is to start documenting it. Moreover I find it in line with an open source project that people build a skeleton for collaborative fleshing-in. Please do go ahead with creating the skeleton as soon you have the time, as this helps out down-stream projects like reX quite immensely in planning and organizing their work. What I'd like to see: 1. TOC 2. Introductions to each chapter 3. A sentence or two with what you want to say, and links to the relevant code 4. A couple paragraphs more for the bigger bits, like the meaning behind the Interfaces, or how robust works Basically enough of a seed to let other people come in and flesh out and grow the documentation. If it's just an empty place-holder, there's no purchase for the thing to grow. Cheers, > 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. > > (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 > _______________________________________________ Opensim-dev mailing list [email protected] https://lists.berlios.de/mailman/listinfo/opensim-dev
