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.
Oh, you gurus of all things documentation..I seek your advice about how to
control an uncontrollable document.
I have been assigned the task of keeping current a requirements document for
our corporate portal, a website from which hangs all sorts of applications,
research, etc. Late last year, the company hired a consultant to take the
requirements, which had formerly been a whole bunch of separate documents,
and combine them into one big document. It's nearly 300 pages (a Word file),
and has hundreds of little embedded graphics (which were unwisely saved as
.bmp files). The consultant used some kind of numbering scheme that seems to
have no real reason for being. There is only a very rudimentary table of
contents, and so poorly organized that you cannot ever know where you are in
the document. It's impossible to use, so it really isn't. I want to make
this document usable, organized, and easy for me to update. I want to split
it back into separate documents.
I just had a meeting with my boss, who shared with me his ideas for
controlling this beast. At first he mentioned using the Word Master
Document feature, and I told him it really didn't work very well (an
understatement, I know). Then he suggested using ClearCase for version
control. (The document currently resides with hundreds of other requirements
documents in Test Director.) I don't know much about ClearCase (we use it
for code, but haven't used it for documentation, as far as I know.)
ClearCase is fine with me, although any opinions there would be welcome,
too.
The real dilemma for me is this: Since I will be splitting up the doc into
smaller pieces, how do I label them? The big document was produced as a
baseline for a major release (2.0) of the portal. Some of these documents
won't have changed at all since that release a few months back. Some will
have changed a bunch, some not very much...you get the idea.
Should they all be labeled with the current release number (like 2.1.8, 2.2,
etc.)? Or does labelling something imply that something inside of it
changed? What about my boss's suggestion that each document have its own
version number (Doc A = 2.0, Doc B = 2.3, Doc C = 2.3.1) that changes when
something inside that document changes?
Whatever we decide to do, I want to start off on the right foot. Thanks in
advance.
Robohelp X3, from eHelp, lets you quickly and easily create
professional Help systems for all your Windows and Web-based
applications, including Net.
Order RoboHelp X3 in May and receive a $100 mail-in rebate, PLUS
free RoboScreenCapture and WebHelp Merge Module.
Order RoboHelp today: http://www.ehelp.com/techwr-l
---
You are currently subscribed to techwr-l as:
archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot- Visit http://www.raycomm.com/techwhirl/ for more resources and info.
