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.
Re: Document Revision History - Front or Back of the Doc?
Subject:Re: Document Revision History - Front or Back of the Doc? From:Keith Hood <klhra -at- yahoo -dot- com> To:Gene Kim-Eng <techwr -at- genek -dot- com> Date:Sat, 21 Jul 2012 20:50:57 -0700 (PDT)
You can also use simple revision numbers. In the vast majority of cases there is really no utility in a laundry list of product changes perpetrated over the years.
Your last sentence is the only really solid reason for having a version history at all - because someone in authority wants it done that way.
Revision histories in civilian documents grew - I believe - out of the procedures the military (or at least the Army) once used to update maintenance manuals and other publications. They were originally guides to tell the users how to make changes in the docs. The maintenance manuals were in 3-ring binders. Every month the DOD would distribute packets filled with change sheets...a new version of the sheet that had pages 3 and 4 front and back, a totally new sheet with pages 4A and 4B that had to be inserted in front of page 5...And in each packet were sheets with a revision table that specified which sheets to pull and which to insert where. We'd have to spend many hours pulling out the old sheets and inserting the new ones. And the revision table had to be put in the front of the document. In addition to being a guide on how to make changes, it was proof that the changes had been made. During IG inspections they would check to see if we had the latest
revision tables in the -20 manuals. So the original purpose of a revision history wasn't a means of telling the user what changes had been made to the item, it was to give supervisors a way to check if people in the maintenance shop had been doing that part of their job right.
Seems to me like the "industry regulations" thing is just a civilian version of that. I can live with that. But I'd still omit a revision history at every chance. One less thing to fiddle with.
________________________________
From: Gene Kim-Eng <techwr -at- genek -dot- com>
To: Keith Hood <klhra -at- yahoo -dot- com>
Cc: Ron Hearn <rhearn -at- central1 -dot- com>; "techwr-l -at- lists -dot- techwr-l -dot- com" <techwr-l -at- lists -dot- techwr-l -dot- com>
Sent: Saturday, July 21, 2012 10:30 AM
Subject: Re: Document Revision History - Front or Back of the Doc?
That's probably true if all your users always only want the most recent revision. But sometimes, different users have different versions of the product and need to know which revision of the document applies to their version. You can usually recognize these cases by revision histories that say things like "added/deleted instructions for Module XXX," or "complies with Specification XXX," or "For use with serial numbers XXX-XXX and above." And sometimes, the history is just mandated by industry regulations.
Gene Kim-Eng
On 7/20/2012 11:53 PM, Keith Hood wrote:
> My take is, why bother having it at all? Why, really, would anyone care how many changes the doc has gone through, and exactly what changes have been made? What does a revision history tell the reader beyond the fact that you didn't get it right the first time?
>
>
> What a reader wants to know most of all is that the doc is complete and accurate NOW. Having a long document history is contraindicated if you really want customer confidence. I figure the longer your revision history, the more likely people are to wonder why did you make so many mistakes and why did you have to go through so many redesigns to get it right? And the more entries there are in the revision history, the more likely they are to wonder if you really *have* finally gotten it right.
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Create and publish documentation through multiple channels with Doc-To-Help. Choose your authoring formats and get any output you may need.
Try Doc-To-Help, now with MS SharePoint integration, free for 30-days.
