[Opensim-dev] User services refactoring status

[Ryan McDougall]

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
>