Re: I had hoped to get more of a response - Re: Managing versions of documents - problems and concerns

[Chris Gooch <chris -dot- gooch -at- lightworkdesign -dot- com>]

Svi Ben-Elya writes:

>Issue 1: Keeping track of which changes were made after the version of a
>document held by a specific customer. How can Technical Support quickly
>identify whether corrections were already included in the document or were
>added later?

When you release software or documentation, tag the files in the
version control system. This marks the particular versions of the files
at that moment, so you can go back to them / compare them to later
versions, etc.


>Issue 2: When more than one person works on a document, how does each
writer
>know what changes have already been made?

Any decent version control system will allow you to see the check-in
or revision history of all files in the system.


>Issue 3: Who made and who authorized a specific change? This can save
>valuable time when problems occur and more information is needed on the
>change and which customer's it affects.

See above; the history of each file will tell you who did the check-in,
and the check-in message. All users will need to adopt a sensible
approach to writing clear and meaningful messages for each checkin
that state what the change is and why it was made ("updated section
on such and such to remove error x; more details in bug report 555")


>Issue 4: When single-sourcing is used, changes and information related to a
>specific document or version of the document.

I'm not sure I understand the question here. If you're single-sourcing
then you only have one source to keep track of, no problems there.
You _can_ check the _output_ files into your version control software
as well as the source files if you want; but you absolutely _must_
check the source files in.


>Issue 5: Document rollbacks. How can I rollback to an old version of a
>document when customers have problems with the newer documentation or the
>product is rolled back? How do I identify what changes made to the document
>are relevant to the older version of the product.

When you build docs for release, think up a product number; I use a fixed
number for each manual combined with a datecode. Tag the source files
you used for the build (see issue 1) against this code number.


>Issue 6: Version Management software commonly used by R&D does not always
>identify changes made to documents.

If you check binary files in, you are correct that most version control
software
will not allow you to see the diffs between files. What you should do is
check
text only files into the system. You mention Framemaker; .mif or .xml files
should work fine in theory, but in practice it's often the case that,
unfortunately,
Framemaker will alter every single line of .mif even if you only made a
simple
change. It might be better with .xml, I'm not sure; worth trying.


>Issue 7: When using a check-out/check-in system and different people work
on
>different chapters (FM files), how do you check for changes to an entire
>book without checking-out all files, thus preventing writers form working
on
>the files.

Any decent version management software should handle this fine. You should
be able to see which files are checked out to who at any stage, without
doing a checkout; if you need to build a file which someone is working on
and you need their edits but they need to continue working they just check
in and then out again; more complex software like perforce or sourcsafe will
allow multiple people to edit files and help you resolve any conflicts; BUT,
if you find that issue 6 is a problem for you then I don't recommend this;
take the conservative approach that Bruce mentions (i.e., writer x
has to check in before writer y can change the file). But remember,
you can check-out a readonly version / resync against a file without
locking it / marking it for edit; this allows you to rebuild without
waiting.


Basically, my advice is to speak to the software people, and adopt
all the same procedures that they do, as far as is practical for you and
your team. Documentation is just another form of software, there's
nothing special about it.

HTH
Chris.

Christopher Gooch, Technical Author
LightWork Design, Sheffield, UK.
www.lightworkdesign.com


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

ANNOUNCING ROBOHELP STUDIO

RoboHelp Studio maximizes your Help authoring power by combining 
RoboHelp Office and RoboDemo, so you can easily create professional 
Help systems that feature interactive tutorials and demos.

Find out more about RoboHelp Studio at http://www.ehelp.com/techwr-l2

---
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.