[Rock-dev] Documentation policy ...

[Thomas Roehr]

On 16.05.2011 11:23, Sylvain Joyeux wrote:
> We right now have 3 places for documentation:
>
>    * the webgen-based documentation (from which rock-robotics.org is
>      generated)
>    * doxygen documentation for packages
>    * the trac wiki
>
> I'm looking for a way to set up a policy -- i.e. what should go where ?
>    * package documentation
>    * general issues
>    * ...
>
> The plusses and minusses of each from my POV:
>
>    * wiki:
>      (+) easy to edit text
>      (-) hard to edit figures: the whole attachment system is pretty
>          annoying. If you want to edit a figure, you need to download the
>          attachment, edit it, re-attach it.
>      (-) Internet connection needed to get the documentation (important
>          when on the field ...)
>      (-) Registration needed.
>    * webgen:
>      (-) need a checkout to edit text and figures
>      (+) once you have a checkout, editing is very easy and can be done
>          offline
>      (-) no immediate display: you have to wait one day to get it pushed
>          to the website, or run rake yourself and look at the result).
>      (+) on the package documentation side, we could have an integration
>          of package-specific webgen pages that get displayed in the
>          package directory.
>      (+) no registration needed.
          (+) well packaged
>    * doxygen:
>      (+) people know doxygen already.
>
> Thoughts ?
The current situation looks ok to me and could be formed to a policy:
Webgen: overall documentation, i.e. giving more the 
architecture/integration view, general workflow, how tools work together.
Doxygen, ..: package documentation, agreeing on one tool per language, 
i.e. C++, ruby, python, ...
Trac/Wiki: for ticket management

-- 
Thomas Röhr (M.Sc.)
Space Robotics

Standort Bremen:
DFKI GmbH
Robotics Innovation Center
Robert-Hooke-Straße 5
28359 Bremen, Germany

Phone: +49 (0)421 178-454151
Fax:   +49 (0)421 178-454150
E-Mail: robotik at dfki.de

Weitere Informationen: http://www.dfki.de/robotik
-----------------------------------------------------------------------
Deutsches Forschungszentrum fuer Kuenstliche Intelligenz GmbH
Firmensitz: Trippstadter Straße 122, D-67663 Kaiserslautern
Geschaeftsfuehrung: Prof. Dr. Dr. h.c. mult. Wolfgang Wahlster
(Vorsitzender) Dr. Walter Olthoff
Vorsitzender des Aufsichtsrats: Prof. Dr. h.c. Hans A. Aukes
Amtsgericht Kaiserslautern, HRB 2313
Sitz der Gesellschaft: Kaiserslautern (HRB 2313)
USt-Id.Nr.:    DE 148646973
Steuernummer:  19/673/0060/3
-----------------------------------------------------------------------