Beefy Boxes and Bandwidth Generously Provided by pair Networks
There's more than one way to do things
 
PerlMonks  

Re: How to write documentation?

by arhuman (Vicar)
on Oct 18, 2001 at 13:34 UTC ( #119636=note: print w/replies, xml ) Need Help??


in reply to How to write documentation?

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
  • In the same document
    Taking care to put the simple abstract part at the beginning and hiding as much as possible the too specifics details (in an APPENDIX for example)
  • In several documents
    This allow you to specialize your documentation to the reader
    (Beccause a techie don't need the same informations as a commercial...)
The second way is my favourite way, I usually make a (very) small doc describing the product
(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 :
  • Write a READABLE way
    Otherwise nobody will (be able to) use it...
  • Adapt your text to your reader (the content AND the form)
  • Don't forget your initial goal
    your technical doc shouldn't become a technical rant about how good the solution is...In the same vein in a commercial documentation, it's totally useless to explain your over-smart technical hack, speak about technological advance ;-)
  • Use spell checkers (It's VERY important for some people (usually your bosses ;-))
  • Use a portable format to allow other people to work on your documentation, convert it...

"Only Bad Coders Code Badly In Perl" (OBC2BIP)

Log In?
Username:
Password:

What's my password?
Create A New User
Domain Nodelet?
Node Status?
node history
Node Type: note [id://119636]
help
Chatterbox?
and the web crawler heard nothing...

How do I use this? | Other CB clients
Other Users?
Others pondering the Monastery: (3)
As of 2021-11-27 03:35 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?

    No recent polls found

    Notices?