Beefy Boxes and Bandwidth Generously Provided by pair Networks
Pathologically Eclectic Rubbish Lister

Re: Writing Good Documentation

by screamingeagle (Curate)
on Jun 24, 2002 at 18:32 UTC ( #176879=note: print w/replies, xml ) Need Help??

in reply to Writing Good Documentation

One should write documentation in a way that it is clear to everyone , not just oneself...put yourself in another programmer's position, who has no idea what the code does, or what its dependencies are. IMHO, it is better to be overly descriptive than to blindly assume a certain level of knowledge on the readers' part.

It's also helpful to make a template document initially, and then make each following documentation page follow the same structure of the template page. This ensures consistency.

A few sections which would be included in every document would be :
a) Purpose of Program: what the code's primary purpose is
b) Database tables used/affected by code
c) Perl Modules (specify exact versions of Perl Modules) required for the code to work
d) Include files used
e) Command-line Parameters passed to the script

I would also recommend completing the documentation within a couple of days of finishing up the final version of your code, cause you would still have everything fresh in your mind...i find that i forget 99% of what i did within a week of completing a project ;-) ...of course, the best approach would be to document the code as you go. HTH

Log In?

What's my password?
Create A New User
Node Status?
node history
Node Type: note [id://176879]
and a kettle whistles...

How do I use this? | Other CB clients
Other Users?
Others examining the Monastery: (1)
As of 2017-09-23 18:21 GMT
Find Nodes?
    Voting Booth?
    During the recent solar eclipse, I:

    Results (273 votes). Check out past polls.