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.
Subject:Re: Code documentation requirements? From:Damien Braniff <Damien_Braniff -at- PAC -dot- CO -dot- UK> Date:Thu, 22 Jan 1998 13:26:44 +0000
I'm not sure exactly what is meant by code documentation. Beth said that
it was the responsibility of the programmers - I tend to agree but am not
fully convinced.
When I first started as a tech author it was documenting software from the
source code where the main tools were multi-coloured pens used to mark the
beginning/end of loops etc! The code WAS commented and came with the
relevant design specs etc.
The lit produced was at four levels (code itself being level 4). The next
level was procedure/process descriptions which gave more detail than the
commented code. The other two levels progressively dropped detail with the
top level being a management overview of the software with little detail.
Personally I found it quite stimulating "cracking" the code and documenting
it and gave me a better understanding of programmers etc. While slow
(approx 60 lines/day was the estimate) the top levels were produced in
double quick time as, by then, you were so familiar with the software. It
made me very wary of programmers though. One procedure we couldn't figure
out what it did and eventually contacted the programmers to be told it was
obsolete and didn't do anything - ignore it. However,every now and then,
we came across code that called this procedure that "did nothing"!!
