[thelist] Re: Basic Documentation Questions

jay.blanchard at thermon.com jay.blanchard at thermon.com
Fri Feb 8 13:41:01 CST 2002


So far everything I have read makes good sense on many levels, but the most
important one that I have read is the one that states...

"...writing the documentation BEFORE writing the first line of code,
but also going so far as to write the user manual before as well...

Ok, so this may not be a basic documentation issue where a web site is
concerned, but it is a good way to start. Flowcharting from one page to the
next, putting code comments where major natural breaks occur and where
mark-up departs from what could be considered best practices. Commenting
any scripting process before or during, never after the fact.

Even the article which I am currently writing documentation on requires
documentation prior to writing the introductory line. It will help to keep
the article structured and logical, it tracks relevant outside resources
(such as links to web sites, photographs, code snippets) and it allows for
some sort of milestone tracking.

Before the first tag goes into the code editor on any, and I mean any,
website where there is a client/developer relationship there should at the
very least be a scope of work outline. This outline can usually be derived
by asking who, what, when, where, how, and why questions.

Jay

<tip type="version identification" author="Jay Blanchard">
One very important document that should be included with any application
(especially since web applications have become prevalent) is the versioning
document. It descibes how to arrive at the version information/description
within a given set of rules. In one company they may use alpha-numeric
versioning such as 5.1a, while others use complicated schemes to keep track
of product versions such as 5.10a.build020502ajb.
</tip>




More information about the thelist mailing list