good chemistry is complicated, and a little bit messy -LW |
|
PerlMonks |
Re: How to write documentation?by arhuman (Vicar) |
on Oct 18, 2001 at 13:34 UTC ( [id://119636]=note: print w/replies, xml ) | 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...). document. 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)
In Section
Meditations
|
|