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.
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.
manify. Embedded in the source code.
API reference documentation
We need generation tools. So the candidates are:
- C :
- php : Multiples
- perl : pod
- python : pydoc
- tcl : tcldoc or doctools
- java : javadoc
- Shell script: shdoc