Beefy Boxes and Bandwidth Generously Provided by pair Networks
No such thing as a small change

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 all is quiet...

How do I use this? | Other CB clients
Other Users?
Others browsing the Monastery: (11)
As of 2017-11-23 15:46 GMT
Find Nodes?
    Voting Booth?
    In order to be able to say "I know Perl", you must have:

    Results (336 votes). Check out past polls.