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.
Carrie Baker wondered: <<Our company has bought 2 or 3 software
applications or parts of them which are integrated in our
applications in some way. We have received their source files in
FrameMaker to put in our FrameMaker template. In one book we took
sections from theirs and reformatted, another used one chapter
reformatted and a third used sections here and there that we added
to. Obviously they will update their software and their files will
change and they will send them to us again, and then we will need to
find out what they changed.>>
A thorny problem indeed. Most of us have more than enough difficulty
keeping up with the last-minute changes in our own products, let
alone in someone else's product.
<<How is the best way for us to work together,?>>
Talk to _them_ and find out! <g> No, really. You need to come up with
something that works for you, but that is so simple and painless for
them that they have no reason to not keep you up to date. The more of
a burden you place on them, the less likely they'll have time to do
the work. If you're basically using their original material unedited
(simply pasting it into your own documents), there's no reason not to
continue doing this: it's working now, and it will continue to work.
If you really want to compare the new with the old to see what
changed, it's going to be difficult to find a simple solution. In
that context, the "best" solution may be something like the
following: When you receive the new software, try following the old
instructions to see if there are any errors and anything that no
longer works. Then consult their new documentation to find out why,
and what to do about it. While you're doing this, skim through the
new stuff to see if they've added features. Add those to your docs.
If this seems like a lot of work, it pays to remember that you should
be doing this anyway. We've all heard of (or experienced) times when
the product changed after the documentation shipped, and the only way
you're going to find this is to compare the docs against the
software. Think of it as basic quality assurance. If you aren't doing
this, perhaps they'd be willing to do so: ship them a copy of your
version of their documentation and ask them to have a quick look and
let you know if there are any problems.
<<How should we ask them to mark the changes made in the
documentation?>>
You have a variety of options. Long ago, someone in this forum
described a plug-in that allows revision tracking in FrameMaker
similar to what Word provides. I don't seem to have details anywhere,
but hopefully that person will see this message and resubmit the
information. Unfortunately, that approach probably won't work,
because if they follow anything like the typical write/revise/publish
process, the original documentation will change several times during
revision before it gets to you, and the only way to see what's
happening would be to receive every revision produced during this
process. Inefficient and awkward, and enough of a burden on them that
they won't want to do it.
If the original documents were reasonably stable, and the revised
versions are likely to be minor patches plus whole new added
sections, you might be able to automate the process using Word. Copy
the original and new Frame text into two Word documents, save them,
then use the "Compare documents" feature (Tools-->Revision Tracking--
>Compare Documents, at least in older versions). This will highlight
the changes and make them easier to see. Does Frame provide a
comparable feature?
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --
Geoff Hart ghart -at- videotron -dot- ca
(try geoffhart -at- mac -dot- com if you don't get a reply)
WebWorks ePublisher Pro for Word features support for every major Help
format plus PDF, HTML and more. Flexible, precise, and efficient content
delivery. Try it today! http://www.webworks.com/techwr-l
Easily create HTML or Microsoft Word content and convert to any popular Help file format or printed documentation. Learn more at http://www.DocToHelp.com/TechwrlList
