[Rock-dev] Documentation policy ...
Thomas Roehr
thomas.roehr at dfki.de
Tue May 17 12:49:03 CEST 2011
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
-----------------------------------------------------------------------
More information about the Rock-dev
mailing list