TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
Tracey Moore wrote:
>we now need to document the code.
>
>How do you document?
But who are you documenting it for? If it is for programmers, then I can
only urge that you forget about creating a document. It is wasteful and
dangerous to document program code externally. My very strong opinion (after
some years as a systems development manager in another life) is that source
code must be documented internally -- that is, in source code comments. At
least then there is a slight chance it will be read by the next person to
work on that code; there is also a chance (much slighter) that it will also
be updated when the code is changed.
Getting programmer's to actually write meaningful comments may be difficult;
getting them to worry about updating other documents, however, will probably
be impossible. The presence of adequate internal documentation should be a
part of any source code control system.
An external document can be useful for providing an overview of the pieces
and how they fit together, but anyone working on an individual piece is
going to want their documentation right before their eyes -- a form of
online help.
All of which reminds me of the contract programmer who once worked for me
and, when ordered to document the modules he had worked on, simply added the
comment "Self-explanatory" to each one. They may not be, but adequate
comments can make them so.
