in reply to
Important preliminary question - Who are your intended audience?
- You, and maybe the other core developers e.g. Maple
- Other programmers using your elegant library or your lovely module e.g. libkdepim or DBI
- Other people installing your cooooool system e.g. Apache, Slashcode
- Normal techy people using the software e.g. R
- Normal non-techy people e.g. OpenOffice
These groups need very different documentation. To produce good documentation you need to know your users. Perhaps the only common thing is that they all need and will benefit from copious annotated examples!