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.
Jim Aikens wrote:
>
> 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.
Speaking as a veteran programmer, I partly agree with this. The
low-level details should most definitely be documented in the code. But
some things are better explained externally (not necessarily in hard
copy, though).
An example would be a large class library or application framework.
Without some sort of coherent and well-organized online reference,
determining the class hierarchies, inheritances, and overrides by simply
rummaging through header files would be a migraine and a half.
Another case where I think external documentation is very useful is an
API. I'd really rather see a well-written textual description of each
interface function organized alphabetically in a hardcopy manual or
online refernece than have to hunt through header files to find out what
the API is capable of and how to get it to do it.
I can't answer Tracey's question, though, without knowing whom the
documentation is for and what it proposes to accomplish.
L.
--
Linda K. Sherman <linsherm -at- gte -dot- net>
Freelance Writer: Technical - Business - Government
