[Opensim-dev] User services refactoring status

[diva at metaverseink.com]

Thanks, Ryan. With help from many people like yourself, we might be able 
to pull this off...

Ryan McDougall wrote:
> On Fri, Jan 8, 2010 at 10:16 PM,  <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
> 
> 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 <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
>>
>