Beefy Boxes and Bandwidth Generously Provided by pair Networks
Perl Monk, Perl Meditation
 
PerlMonks  

Re: How to write documentation?

by pjf (Curate)
on Oct 18, 2001 at 13:56 UTC ( [id://119639]=note: print w/replies, xml ) Need Help??


in reply to How to write documentation?

G'day ajt,

It sounds like you're already got a great start with the whole documentation thing. The following isn't really advice, it's more a relating of my own experience and what's worked for me.

User Documentation
I've tended to prefer to use a version management system such as CVS rather than making hard-copies at every stage. With CVS it's very easy to see the difference between versions, to track who made which changes and when, and to maintain multiple branches of the software if necessary. Of course, CVS does have a bit of a learning curve, and non-technical people take quite some time to get used to it, even with a graphical interface.

For user documentation, I've found the best way is to get a user to write it. Seriously. There'll be things which neither yourself nor your fellow developers will think to document, simply because they're so obvious you'll never think of them. I've been at workplaces where the user documentation was always written by non-technical people for that very reason.

Documentation is like software in many ways, in that it also needs to be tested. The best people to test are those who aren't already familiar with the software, and haven't had you drop a previous copy of the user manual on their desk. I always exist my test population much too quickly. ;)

Technical Documentation
For technical documentation, find a document that you find really useful, and copy the layout. POD is fabulous for tech docs because you can have the documentation sitting next to the code it refers too -- nobody can lose the documentation or be too busy to look it up.

I try to document every function -- what it's purpose is, an y bugs or unexpected behaviour it might have, and an example of use if it's not immediately obvious. Good, clean code is often self-documenting, and that's certainly something worth aiming for.

Each file should also (at a minimum) have some header documentation stating the purpose of the file, when it was written, and who by. This means someone can quickly and easily find if they're in the right place without having to look at code.

Keeping an FAQ is also very useful. Usually the same questions keep appearing again and again. These are obviously things you want to document.

Cheers,
Paul

Replies are listed 'Best First'.
Re: Re: How to write documentation?
by zuqif (Hermit) on Oct 18, 2001 at 14:36 UTC
    Just as an aside, I also subscribe to having the users write their own documentation.
    This has numerous advantages:
    • They gleen a more formal understanding of your solution to the problem
    • Its more likely to be complete -> not missing 'coder-obvious' elements
    • Its 100% technical-jargon-free!
    • You dont have to do it yourself!
    Of course, am sure you could generate a framework template from your code for them to fill in (:
    the 'qif;

Log In?
Username:
Password:

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

How do I use this?Last hourOther CB clients
Other Users?
Others chilling in the Monastery: (8)
As of 2024-03-28 09:34 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?

    No recent polls found