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.
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
system.
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
my
career (elevators, escalators, & office machine products - had its
ups&downs
;-), including internationalization/translation for world markets. But
I'm
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
that
release, and finally v2.0 for a full re-write, and so on. Documentation,
of
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
we
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
software
(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
simply
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
what
happens in software).
* Is the Company remarketing a 'new & improved' product? - or are you
just
changing (correcting?) the manuals (for the SAME product)? Also, is your
company really republishing the manuals for what you call 'design'
changes
(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
for
all translated versions, why not use the same version designation
(except
perhaps adding a coding for the specific language)? I would imagine that
the
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
skips
for international versions is simply a recipe for disaster.
Anyway - sorry, Mats, I'm not sure what the final answer is ... please
give
me more details and I'll try again.
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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: http://www.ehelp.com/techwr-l
Help celebrate TECHWR-L's 10th Anniversary starting this month!
Check out the contests at http://www.raycomm.com/techwhirl/special/contests/
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 http://www.raycomm.com/techwhirl/ for more resources and info.
