Documentation process?

["Geoff Hart" <Geoff-h -at- mtl -dot- feric -dot- ca>]

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 
reviews).

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 
suspect 
that it is only a pernicious, Pythagorean coincidence." George Miller, "The Magical Number Seven" (1956)