Documentation process?

Subject: Documentation process?
From: "Geoff Hart" <Geoff-h -at- mtl -dot- feric -dot- ca>
To: TECHWR-L -at- lists -dot- raycomm -dot- com
Date: Wed, 29 Sep 1999 09:38:27 -0400

Josee Morel is seeking <<...assistance with a restructuring
issue at work. I work in France for a French software firm
with two French technical writers. I am the only one working
on the English version of the documentation. Recent
market changes have pushed management to ask us to stop
producing doc in French and work together to produce the
doc in English.>>

Why have you abandoned your French market? It seems to
me that for relatively little extra effort, you can also produce
the documents in French. For example, I work in a fully
bilingual environment (about half my authors are French),
and we publish everything bilingually (separate English and
French versions). The first-language version can take months,
particularly given how many reviews (internal and external)
are involved; the translation rarely takes more than a couple
of weeks. And that's in an environment where we have a few
dozen reports circulating at any point in time.

<< His first proposal was to have my co-workers write
directly in English.>>

We've found that very few of our authors can write well
enough in their second language for this to be an efficient
approach. Even when they write well, it takes them much
longer to produce a good draft, and that lowers the overall
productivity of the publishing process. For us, it's been far
more efficient for the French authors to write in French, with
me translating the documents after I've edited them (and a
contractor doing the grammar part of the edit after I've done
the substantive work); for English authors, we do much the
same thing but the external contractor does the French
translation after I do a full grammar plus substantive edit.
Apart from being efficient, it also addresses one very
important problem with having people write in a second
language: the technical reviews are generally of poor quality
when they are conducted in the author's second language.
That could be a crucial point in your situation; even if it's not
crucial, working solely in English will decrease the quality of
the results.

<< I would be responsible for proof-reading this work.>>

You indicated later in your message that you're a junior
technical writer, but didn't mention anything about your
language skills. From the skill with which your message was
written, your English seems pretty good, but there are
occasional hints (e.g., saying "proof-reading" rather than
"proofreading" or--far more correctly--"editing") that suggest
you're not as fluent as a native. I'm not saying this to criticize
your language skills, just to point out that if you're publishing
in a second language, it's always a good idea to have a native
check your work. For example, I'm good enough at French to
translate it, and even to write relatively clearly in French, but
I'm simply not good enough to write fluently and correctly
and quickly in my second language. Are you sure that you're
good enough?

<<Since they are not native speakers, my work would be
doing a lot of rewriting in addition to my regular work.>>

See above. As you noted, this is not a time- or cost-efficient
solution, and it's likely to introduce problems with accuracy
and correctness. It's also likely to cause you problems, since
you'll undoubtedly be expected to do your own work as well
as fixing your colleagues' work.

<<Could you help me break down the process involved in
producing documentation?>>

The outline you proposed seems pretty good to me, with a
few exceptions and notes. First, I'd combine audience
profiling and task analysis, since the two are inseparable and
since breaking them into two phases may take much more
time, depending on how you actually do the work. Second, if
by "researching" you meant "researching technical details of
the product", then that step should follow the audience and
task analysis, not precede it. Consider, for example, an
audience that doesn't need procedural details (e.g., they're
experts who already know general procedures for your type
of product) but _does_ need to know how your product fits
into a larger context (e.g., these same experts need to know
how it works and integrates with other products; once they
know that, they can figure out the procedures themselves).
Audience analysis would tell you that you can spend far less
time on recording procedures than on explaining context, and
on providing tips on how the procedures they already know
must be adapted for that context.

I also didn't see any indication of where you include editing
and review in the process. I assume you've left these implicit
in the phases labeled "draft", but you need to make them
explicit steps of their own. Define carefully the types of
review (editorial, technical, and audience usability reviews)
you need to perform, and who takes final responsibility for
ensuring the reviews are done correctly. I've found that the
most efficient times for editing are _before_ internal and
external reviews (so reviewers can concentrate on the facts
and the substance, not the writing style), and _before_ final
approval (to catch any problems that escaped the previous

The other big point is that if you accept my suggestions about
translation, then you should include a translation phase after
the phase you called "writing final draft". Although you can
often translate after the beta draft, there are likely to be
enough changes subsequently that this becomes inefficient;
for example, when I do this kind of translation under deadline
pressures, I have to spend the remainder of my time on the
manuscript making sure that changes to the French version
get incorporated in the English version too (and vice versa).
For some of my authors, this isn't a problem; for others, it's a
very big problem, and may even lead me to do a final word-
by-word comparison of the two versions.

<<I would also like to see some of your time estimates (in
percentages) for each of these phases Different phases do not
depend on good writing skills.>>

There's no way for us to provide useful time estimates, since
we don't know how fast you and your colleagues work, the
magnitude of each task for your particular product and
audience, or how efficient your review process will be. If
you're just beginning to set up a documentation process,
now's the best time to start recording these times so you can
use them for future planning.

--Geoff Hart @8^{)} geoff-h -at- mtl -dot- feric -dot- ca (Pointe-Claire, Quebec)
"Perhaps there is something deep and profound behind all those sevens, something just calling out for us to discover it. But I
that it is only a pernicious, Pythagorean coincidence." George Miller, "The Magical Number Seven" (1956)

Previous by Author: Copyright blurb?
Next by Author: Easter egg recognition?
Previous by Thread: STC Research Grants and Special Opportunities Grants
Next by Thread: OT: then and now

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

Sponsored Ads