[Opensim-dev] User services refactoring status

[Justin Clark-Casey]

diva at metaverseink.com 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 <diva at metaverseink.com <mailto:diva at metaverseink.com>>
>>
>>     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
>>     Opensim-dev at lists.berlios.de <mailto:Opensim-dev at lists.berlios.de>
>>     https://lists.berlios.de/mailman/listinfo/opensim-dev
>>
>>
> _______________________________________________
> Opensim-dev mailing list
> Opensim-dev at lists.berlios.de
> https://lists.berlios.de/mailman/listinfo/opensim-dev
> 


-- 
Justin Clark-Casey (justincc)
http://justincc.org
http://twitter.com/justincc