Beefy Boxes and Bandwidth Generously Provided by pair Networks
Just another Perl shrine

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 nobody stirs...

How do I use this? | Other CB clients
Other Users?
Others surveying the Monastery: (2)
As of 2018-02-25 14:22 GMT
Find Nodes?
    Voting Booth?
    When it is dark outside I am happiest to see ...

    Results (312 votes). Check out past polls.