[Rock-dev] Documentation policy ...

[Sylvain Joyeux]

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.
  * doxygen:
    (+) people know doxygen already.

Thoughts ?
-- 
Sylvain Joyeux (Dr.Ing.)
Space & Security Robotics

!!! Achtung, neue Telefonnummer!!!

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

Phone: +49 (0)421 178-454136
Fax:   +49 (0)421 218-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
-----------------------------------------------------------------------