[ESPResSo-devel] Developer's documentation format

[Olaf Lenz]

Hi everybody!

Besides the pure source code docs of ESPResSo, there are a number of
other documentation pieces for ESPResSo that partly exist and partly
should be written:
  * How to use git for ESPResSo development
  * Coding conventions for ES
  * How to add files to ES
  * Using and modifying the build system
  * Programmer's Guide ("Under the hood")

However, at the moment I am not sure in what format and where to put
this kind of documentation. So far, this kind of stuff was supposed to
go into the "Developer's Guide" which was written in the Doxygen format
and bundled with the source code documentation. However, I have the
feeling that it was very hard to access the Developer's Guide and also
to modify it, as Doxygen has a very strange format for additional
information.

I can think of a number of options, but I do not know which one to use:

* Using doxygen (as it was so far)
  * Pro: code documentation and developer's docs together
  * Con: nasty doxygen format
  * Con: confusing doxygen docs
  * Con: hard to edit
  * Con: not always up-to-date

* In the ESPResSo-wiki on http://espressomd.org
  * Pro: easy to edit
  * Pro: always up-to-date
  * Con: only available when online
  * Con: yet another account, yet another format

* In an extra LaTeX-PDF-document, or as part of the UG
  * Pro: comes with source code
  * Pro: same format as UG
  * Con: hard to edit
  * Con: not always up-to-date

* Using GNU Savannah's documentation features ("Cookbook")
  * https://savannah.nongnu.org/cookbook/?group=espressomd
  * Pro: location where it would belong to "naturally"
  * Con: yet another format format
  * Con: confusing page

Does anyone of you have suggestions which one of these options to
choose? Or does anyone have another idea?

I believe that I would prefer either the wiki or the LaTeX document, but
I'm open for other ideas.

Olaf

-- 
Dr. rer. nat. Olaf Lenz
Institut für Computerphysik, Pfaffenwaldring 27, D-70569 Stuttgart
Phone: +49-711-685-63607

olenz.vcf
Description: Vcard