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.
Michelle Prejs reports: <<My department is defining it's online standards.
I'm researching how other companies and writers track revisions for testing
and review.>>
Currently, we do almost all editing of our printed materials in Word using
its built-in revision tracking tools, and it's worked wonderfully well. By
management edict <g>, we're also using versioning, which I distrust (based
on reports from other techwhirlers) but which has worked fine so far despite
that. On the other hand, we haven't tried this approach in online help. In
principle, I don't see any reason why the same approach wouldn't work, but I
haven't had the time to set up a test project and see whether the
interaction between RoboHelp and Word (which is already more fragile than
I'd like) would have any grave repercussions. The last time we did a major
review and revision of a help system, we did it on paper printouts of the
help file, but largely because the reviewers hadn't had time to learn
revision tracking. Now that we've got them trained, I'm planning to correct
this.
The one moderately serious obstacle to this approach that I can foresee is
that since the developers won't have a copy of RoboHelp, they may have
difficulty opening and working in the files I send them, or might
conceivably trash something in the files. For example, opening a file with
embedded RH macros and template information might cause some nasty problems
on a system that doesn't have RoboHelp installed. Anyone else tried this?
Good or bad news? One way to work around any potential problems might be to
create the file in Word but outside RH, then review it for technical content
and editorial matters _before_ creating the help file. Once the content is
approved, you could then import the file into RH and build the links and
keywords. Not as elegant a solution as using revision tracking directly
within RoboHelp, but perhaps a workable way to proceed.
<<We currently use Robohelp to develop our online help. They suggest using
Build Tags. The way I understand this is, you would create a topic to track
your revision history, but not publish it with the online help.>>
You could probably succeed in this manner, but that's not really the purpose
of build tags; these are used to let you compile different versions of a
help file and it's easy to foresee a situation in which a simple typo while
entering a build tag results in leaving a section of review comments in the
final help file. If all you need to do is track who saw a document and when,
it would be easier to use Word's "Insert comment" feature, since that
accomplishes the same effect, but is easier to control; when you're ready to
compile the file, simply open the View menu and select "Comments", then find
each comment and delete it. (For that matter, you can search for comment
markers in Word; in the Find dialog box, click the "More" button, then the
"Special" button, then select "Comment marker".)
My reservations about proceeding in this manner involve the fact that it
would be difficult to find out and approve or reject the specific changes
that each reviewer makes, and this greatly increases the possibility of
introducing errors. The "Compare documents" function is cranky and
unreliable in Word, and worse yet, it doesn't tell you who made each change.
Revision tracking resolves both issues, and thus is probably a better
approach.
Sue Gallagher mentioned that if your developers are using version control
software, you should consider learning to use it to control your help
documents too. I second the motion. I don't follow this approach because
this software is expensive and is not in the budgetary future, but it's easy
to fake a version control system simply by keeping dated backups of each
working file. You lose the automated sign-in/sign-out control, but there are
workflow solutions (human, not software) you can adopt to resolve this
issue.
--Geoff Hart, FERIC, Pointe-Claire, Quebec
geoff-h -at- mtl -dot- feric -dot- ca
"User's advocate" online monthly at
www.raycomm.com/techwhirl/usersadvocate.html
"How are SF writers like technical writers? Well, we both write about the
things we imagine will happen in the future!"--Sue Gallagher
*** Deva(tm) Tools for Dreamweaver and Deva(tm) Search ***
Build Contents, Indexes, and Search for Web Sites and Help Systems
Available now at http://www.devahelp.com or info -at- devahelp -dot- com
A landmark hotel, one of America's most beautiful cities, and
three and a half days of immersion in the state of the art:
IPCC 01, Oct. 24-27 in Santa Fe. http://ieeepcs.org/2001/
---
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.
