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:System Documentation and Help! New Job... From:Bruce McCowan <bmccowan -at- GR8DANE -dot- COM> Date:Fri, 2 Oct 1998 16:06:15 -0400
Bruce McCowan wrote:
>
> I am hoping for some opinions on what constitutes good system
documentation
> for a Windows application...
Many thanks to all who supplied comments and ideas re "good" System
Documentation for a Windows application. The summary would seem to be --
"the more information the better and go on-line, linking to the code".
Please accept my apologies for the delay.
I've got a few thoughts on the matter myself. In many ways, it seems to come
down to a best definition of the document readers who are in the "big" part
of the Bell curve, that is in this case, the "average application
maintenance / enhancement person". But, of course, this will depend on how
the readers and their management define their needs and wants in connection
with code maintenance and application enhancement. Perhaps beginning with a
graphical and textual overview of the business requirements vis a vis the
code / GUI and data flow diagrams etc. and then drilling down to more detail
(with lots of feedback cycles) is a good idea.
I really do believe that the system documentation cycle should run in
parallel with the application development cycle, right from the functional
specification / business requirement phase. This should result in the
recording of design decisions, which, I imagine, will be useful to have
around when there is discussion of proposed "enhancements". (In other words,
an "enhancement" may have already been debated and rejected.) All of which
sounds a bit like the programmer / analyst should probably document his /
her own application, save for the fine-tuning and formatting by the tech
writer at various stages.
Further comments would certainly be appreciated. Thanks again.
PS: Some of my comments might be of interest in the discussion of "Help! New
Job?".
Bruce McCowan, P.Eng.
Great Dane Consultants
416-485-4623
Fax 485-3136
bmccowan -at- gr8dane -dot- com
