I completely agree w/ john_oshea and tirwhan. It is very difficult to write good documentation, as I've said before, but not quite so eloquently.
To handle trying to write docs for multiple audiences -- sometimes, you need to just write multiple sets of documentation. Eg, it makes sense to place normal usage info in the POD, while placing information about hacking the code in line comments within the program.
For those times when I've had to write documentation for end users, there are two methods that work best for me -- flesh it out based on questions asked by the users, but even better is to write the documentation before you write any code.
As strange as it may sound, it's sort of like using XP techniques -- instead of writing tests first, you explain how the program is expected to work ... and from there, you write examples, which get turned into test cases ... and then you write the code.
It lets you think about how your program / module / whatever fits within a larger system ... it also forces you to try to keep the interfaces simple, so that you can more easily document them. (resulting in it being friendlier software for people to use, typically.)
As for covering all of the basis -- use some of the module templates, and look at the different sections they have, or look at documentation for similar applications. Documentation is never really done, as you'll always have the trickle in of questions, and you refine the documentation to clarify things (hopefully without making other things more confusing in the process)
In reply to Re: creating documentation
by jhourcle
in thread creating documentation
by stonecolddevin
| For: | Use: | ||
| & | & | ||
| < | < | ||
| > | > | ||
| [ | [ | ||
| ] | ] |