So these are my ideas on how to document projects. There are three types of documentation types:
- User guides
Targetted and end-users of the software and people who want a brief overview. - Man pages
Again targetted at end-users but also sysadmins. Usually to address a specific feature. - API level documentation/reference guide.
Targetted at programmers enhancing, maintaining the software.
To generate I would use different tools. In general we would like to embed with source code.
User Guides
Either as a stand alone document or embedded in the code. My default tool is to use Markdown as can be easily be converted to HTML or PDF as needed.
Man pages
Use manify. Embedded in the source code.
API reference documentation
We need generation tools. So the candidates are:
- C : zehdok
- php : phpdoc
- perl : pod
- python : pydoc
- tcl : tcldoc
- java : javadoc
- javascript : jsdoc-toolkit
Multi languages:
