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
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
|
|---|
In Section
Meditations