Beefy Boxes and Bandwidth Generously Provided by pair Networks
The stupid question is the question not asked
 
PerlMonks  

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


Comment on Re: Writing Good Documentation

Log In?
Username:
Password:

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

How do I use this? | Other CB clients
Other Users?
Others cooling their heels in the Monastery: (15)
As of 2014-07-10 21:27 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?

    When choosing user names for websites, I prefer to use:








    Results (216 votes), past polls