|There's more than one way to do things|
Re: How to write documentation?by arhuman (Vicar)
|on Oct 18, 2001 at 13:34 UTC||Need Help??|
For my part I tend to write documentation as I write code :
I wrote a general (abstract) documentation, then I add more detailed parts.
(then I iterate the second phase until satisfied).
Note that you can do it
(just to make the reader understand what we're talking about)
I then write a more detailed document with links to several other (specialized) docs (Appendix, user guide, maintenance guide, sysadmin's guide, developper's guide...).
Last note: 'the quick install' and 'common troubleshooting' parts seems to me the most used part of a technical docs
(at least at my office), it may be worthy to write them with a special care...
UPDATE : The 'links/resources' part is also a must write to my mind...
UPDATE 2: As I realize that my answer may be far from practical, I'll add some common useful guidelines :
"Only Bad Coders Code Badly In Perl" (OBC2BIP)