RE: Revision identity issues

Subject: RE: Revision identity issues
From: "Broberg, Mats" <mats -dot- broberg -at- flir -dot- se>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Wed, 30 Apr 2003 21:29:38 +0200


Thanks for your reply.

Your first question:

No, that's my point. I don't think it is a great idea to issue a manual for
a new product where the version of the manual will, for example, be "ver.
2.1". However, is it a problem in the customer end? I'm not sure, but I
don't think so. The customer will only see the 2.1 manual and will probably
not wonder about why it is 2.1 and not 1.0. They will probably only pay
attention to the version number when we ask them to.

Your second question:

The company develops the products during their whole lifecycle and offer
updates, extra options etc. These are the things I revise, as well as the
inevitable errors that plague technical manuals...

Your third question:

Yes, we do republish manuals quite frequently. This is not as expensive as
it sounds. Due to the design of the XML-based documentation system, many
corrections can be automated by a specific feature in the system that
compares identical XML nodes in the different languages. We batch-compose
150 manuals in a little more than 3 hours, using XEP from RenderX. The PDF
files are saved in a folder to which the (digital) printing company has
access. They produce the manuals based on production figures in our ERP

Your fourth question:

Well, this is what I am aiming for and was asking you about - to use the
same version number for English as for Korean.

Best regards,
Mats Broberg

-----Original Message-----
From: Gillespie, Stephen (Contractor)
To: Techwr-L (E-mail)
Cc: mats -dot- broberg -at- flir -dot- se
Sent: 2003-04-30 20:50
Subject: FW: Revision identity issues

hi, Mats
Yours is a complex problem (I read your post several times, still not
sure I
fully understand ;-). I prob have more questions than answers, but
here's my
2 cents:

I wrote/edited technical docs in manufacturing for the first 10 years of
career (elevators, escalators, & office machine products - had its
;-), including internationalization/translation for world markets. But
now in software development support. What you are describing sounds more
like CM for software ...

For software, of course each release is versioned using some kind of
incremental/sequential numbering system, e.g. v1.0 for baseline, 1.1 for
next (full) release, 1.1.1 for a minor release (usually a bug fix) for
release, and finally v2.0 for a full re-write, and so on. Documentation,
course, is labeled/titled to match the software versions.

CM (configuration management) is another issue. We use the Rational
ClearCase tool for CM control. On top of that, all artifact deliverables
(code, models, and documentation) are embedded with an in-house scheme
call a CI number (configuration item), which is a 19 character
(alpha-numeric) code - but I won't bore you with the details.

So, the principle for software documentation is that it matches the
(code) designation. Hardware may be another story.

For your dilemma, my questions include,
* for a hardware product, how can you have an increment in the control
number for a NEW product? In other words, product Model A has its own
operator's manual; product Model B (even though a common practice of
renovating Model A) will have its 'own' manual, uniquely identified,
etc. In
other words, maybe product Model B could be designated 2.0 (which is
happens in software).

* Is the Company remarketing a 'new & improved' product? - or are you
changing (correcting?) the manuals (for the SAME product)? Also, is your
company really republishing the manuals for what you call 'design'
(meaning, simply a 'better way to show/tell' something about the
product)? I
cannot imagine being able to justify the cost for that.

* Similarly, if the English product and manual version is the baseline
all translated versions, why not use the same version designation
perhaps adding a coding for the specific language)? I would imagine that
international product might also have different features/functionality,
which would require the manual to have slightly different content.

Your whole scenario describing 'designing' vs. 'content' changes, then
for international versions is simply a recipe for disaster.

Anyway - sorry, Mats, I'm not sure what the final answer is ... please
me more details and I'll try again.

Steve Gillespie

Sr Technical Writer
Science & Engineering Associates, Inc
Naval Personnel Command
5720 Integrity Drive
Millington, TN 38055-3100

Last chance to order RoboHelp X3 and receive a $100 mail-in rebate,
PLUS free RoboScreenCapture and WebHelp Merge Module. Offer expires
4/30/03! Order here:

Help celebrate TECHWR-L's 10th Anniversary starting this month!
Check out the contests at
Happy birthday to you, happy birthday to you, happy birthday TECHWR-L....

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 for more resources and info.

Previous by Author: Revision identity issues
Next by Author: Re: Revision identity issues
Previous by Thread: RE: Revision identity issues
Next by Thread: Re: Revision identity issues

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

Sponsored Ads