Re: maintaing a list of changes in User Guides between versions.

Subject: Re: maintaing a list of changes in User Guides between versions.
From: "D. Michael McIntyre" <michael -dot- mcintyre -at- rosegardenmusic -dot- com>
To: techwr-l -at- lists -dot- techwr-l -dot- com
Date: Mon, 5 Feb 2007 10:34:46 -0500

On Monday 05 February 2007 7:11 am, Caroline Tabach wrote:
> Someone asked us if there is any way that we keep track of changes
> that are made in our user guides/helps from version to version.
>
> Is this something that people do?

In the open source world (Linux only, in my case, not cross-platform), we
commit changes incrementally to CVS (Code Verification System) or Subversion
repositories. This way you can get a record of what you did to what when, or
a record of everything between then and now. You can roll back to some
previous point in time, etc. This works much better if the document sources
are in non-binary formats, because binary commits (eg. screenshots) are a
simple total replacement of X for Y.

I haven't ever really tried to use this to get a history of the progression of
documentation per se, but it's great for pulling out a set of release notes
to show the users what changed since the last release of the application.
I'm sure it's applicable to documentation too, if I had ever had some reason
to look.

Let's see... You can use this to show who did what when (the numbers are
revision numbers, and can be correlated to a date and time). Here's a little
sample using svn blame to show who wrote which bit of this help file:

7473 dmmcintyr "Allegro" offered as a parallel alternative to
typing, LilyPond
7473 dmmcintyr preview, assorted smaller features, many bug
fixes
7473 dmmcintyr </para></listitem>
7473 dmmcintyr <listitem><para>
7420 cannam 1.2.4 &ndash; July 2006: bug fixes
7420 cannam </para></listitem>
7420 cannam <listitem><para>


As far as who did what when, and what changed from what, you can pick a target
revision number, or a date, and compare it to some other date. A few lines
from one day in 2003, and then the same lines on the same day in 2006:

2003:
4408 dmmcintyr Invokes an event filter dialog.
4408 dmmcintyr </action>
4408 dmmcintyr This offers you the ability to filter a
range of events in
4408 dmmcintyr any of several categories out of your
selection.
4408 dmmcintyr </para>
4408 dmmcintyr <para>
4408 dmmcintyr <screenshot>


2006:
4408 dmmcintyr Invokes an event filter dialog.
4408 dmmcintyr </action>
5921 cannam This offers you the ability to filter a
range of events in
5921 cannam any of several categories out of your
selection.
4408 dmmcintyr </para>
4408 dmmcintyr <para>


As this random example shows, it also lets you look back and wonder what
someone who followed you thinks he changed when he edited something you
wrote. I don't see any difference between his revision 5921 lines and my
revision 4408 lines. It must have been a whitespace change or something.

Anyway, this is probably sufficient to give you some idea how version control
might be useful for documentation, even if I've never had any real occasion
to actually use this technology for this purpose. I hope this was helpful,
even though I'm writing from way out here at the edge of the Earth on the
Linux music software frontier.
--
D. Michael McIntyre
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Create HTML or Microsoft Word content and convert to Help file formats or
printed documentation. Features include single source authoring, team authoring,
Web-based technology, and PDF output. http://www.DocToHelp.com/TechwrlList

Now shipping: Help &amp; Manual 4 with RoboHelp(r) import! New editor,
full Unicode support. Create help files, web-based help and PDF in up
to 106 languages with Help &amp; Manual: http://www.helpandmanual.com

---
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 admin -at- techwr-l -dot- com -dot- Visit
http://www.techwr-l.com/techwhirl/ for more resources and info.


References:
maintaing a list of changes in User Guides between versions.: From: Caroline Tabach

Previous by Author: Re: The 'user' in User Manual
Next by Author: Re: Report Report Report
Previous by Thread: RE: maintaing a list of changes in User Guides between versions.
Next by Thread: Re: maintaing a list of changes in User Guides between versions.


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


Sponsored Ads