Tracking changes in outside documentation?

Subject: Tracking changes in outside documentation?
From: Geoff Hart <ghart -at- videotron -dot- ca>
To: TECHWR-L <techwr-l -at- lists -dot- techwr-l -dot- com>, Carrie Baker <carriebak -at- gmail -dot- com>
Date: Wed, 20 Sep 2006 09:27:23 -0400

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)

www.geoff-hart.com

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -


^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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

---
You are currently subscribed to TECHWR-L as archive -at- infoinfocus -dot- com -dot-
To unsubscribe send a blank email to techwr-l-unsubscribe -at- lists -dot- techwr-l -dot- com
or visit http://lists.techwr-l.com/mailman/options/techwr-l/archive%40infoinfocus.com


To subscribe, send a blank email to techwr-l-join -at- lists -dot- techwr-l -dot- com

Send administrative questions to lisa -at- techwr-l -dot- com -dot- Visit
http://www.techwr-l.com/techwhirl/ for more resources and info.


References:
tracking changes in outside documentation: From: Carrie Baker

Previous by Author: Translation of on-screen menus?
Next by Author: Acrobat 8?
Previous by Thread: tracking changes in outside documentation
Next by Thread: re poets as tech writers and programmers


What this post helpful? Share it with friends and colleagues:


Sponsored Ads