[simspark-devel] documentation effort

[Joschka B. <jbo...@un...>]

Hi all,

as you all know and many of you experienced painfully, to this day,  
there is no complete manual for users and developers of our simulator.  
Some information is available, but it is scattered over text files,  
master's thesis, different Wiki and web pages, incomplete manuals, and  
the mailing list archives. This makes it very hard for newcomers to  
get started, and it results in the same questions being asked on the  
mailing lists time and again. I think this is not a desirable state,  
and with an organized effort, we should be able to change this rather  
quickly.

I think we need at least a "getting started" guide, an F.A.Q. list, a  
user manual, and a developer manual. To get an idea of what I would  
like to see (concerning quality) for a manual, please have a look at  
[1]. This is the beginning of a manual that Oliver Obst started a  
while ago. Rodrigo da Silva Guerra also did an excellent job creating  
a manual for the Mixed Reality robots which you can find in the  
repository of [2]. I'd like to see something of similar quality for  
our simulator.

Concerning the contents of the user's manual, I think the manual of  
the 2D simulator can be a good example to follow. Even though it is a  
bit dated by now, it's organization has stood the test of time and it  
has been useful for many people to get started, and keep going using  
the simulator. Besides that, we have resources like the manual Markus  
Rollmann started in the sserver CVS (docs/manual in the rcssserver3d  
distribution), and the well known TEXT_INSTEAD_OF_A_MANUAL text file.  
Markus' manual contains information for both users and developers, and  
should be distributed accordingly. Also, there are different  
installation instructions and getting started pieces scattered over  
the net (I'm not aware of them all, please give me a yell).

Everybody on this mailing list is using the simulator, and everybody  
can contribute at least some part to a manual I think. You all  
depended on someone giving you information on how to get started with  
this strange, complicated piece of software, so maybe you can give  
something back now :-)

Concerning the developer's manual, we have Marco's thesis at [3], and  
Markus' thesis at [4], Oliver's and Markus' journal paper [5], plus  
information contained in Markus' manual mentioned above. Everybody who  
has ever ventured to touch the code, or just read parts of it (or  
plans on doing so), is welcome to contribute.

The F.A.Q, the getting started guide, and maybe some HOWTOs (e.g. how  
to export models from Blender to SimSpark, how to create a new robot,  
etc.) could be placed in the simspark wiki at [6]. (A note concerning  
this: we're still planning on moving the simspark code to the simspark  
repository completely at some point, but right now, this would be too  
much work. Actually, Hedayat ist now porting improvements from that  
repository back to the sserver one, and once this is complete, we can  
do the transition, I hope.)

For the organization of the documentation effort, I think it would be  
good to have a dedicated individual (maybe one for user and one for  
developer manual), or a small group. They should determine the  
contents, assign work to volunteers, and do the final editing. If  
you're interested to help out with this, please contact me. But again,  
overall, this has to be a community effort.

Alright, let's get started :-) Maybe if we're good, sometime in the  
future then, we won't ever have to reply an email with "Please set  
your LD_LIBRARY_PATH variable to..." ;-)

Cheers,
Joschka

[1] http://www.oliverobst.eu/tmp/hope-1.pdf
[2] http://sourceforge.net/projects/pv-league/
[3] http://www.uni-koblenz.de/~fruit/ftp/teaching/koe03-diplomarbeit.pdf
[4] http://www.uni-koblenz.de/~fruit/ftp/teaching/rol04-diplomarbeit.pdf
[5] http://www.oliverobst.eu/publications/2005/spark-OR05.pdf
[6] http://simspark.sourceforge.net/wiki/