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.
Automating documentation (a bit long, but I need your help!)
Subject:Automating documentation (a bit long, but I need your help!) From:John David Hickey <jdavid -at- FARABI -dot- COM> Date:Wed, 22 Jul 1998 10:15:51 -0400
Greetings!
I know, I know... The subject line gives me the willies too. But my project
leader asked me what I could find out about automating the process of
documentation, so I gotta give it an honest effort.
When the developers have a new version of the code ready, they can send a
patch to customers that simply updates their application without replacing
the whole thing. This preserves whatever configuration/information the
client had and gives them more flexibility/power.
My company would like to know if there's a process out there that would
allow you to simply insert information about new features to a task-oriented
document when they become available rather than rework the entire document.
Ideally, the document would look something like this:
Chapter 1: Overview of Hungarian Widgets for Windows
Chapter 2: Installing Hungarian Widgets for Windows
Chapter 3: Creating your Hungarian Widgets
Chapter 4: **New Feature**
Chapter 5: **New Feature**
Everytime the application would have a new feature added in, the author
would only need to add a new chapter at the end of the book.
With a task-oriented manual, this is not possible because new features tend
to change procedures, so the entire book needs to be looked over. You could
make the manual reference-only, but then the reader's understanding suffers
(he'll know what each component does, but may not understand how the program
meets his need).
My initial suggestion was to convert the User's Guide to HTML and have the
users access it from the company's website. They could then receive email
notification when releases are made. This didn't excite my project leader
like I hoped it would.
Any ideas out there? Is it possible to automate the documentation process,
or do you have to choose between task-oriented and reference manual? Are
there any tools that can help you do this?
--
Be seeing you,
Dave
---
jdavid -at- farabi -dot- com
Lone Writer at Farabi Technology Corp.
Montreal, Quebec
4000+ readers? I Am Drunk With Power! <maniacal laughter>
---
