Re: Condensing large technical manuals

[CASSIN Gilles <GCassin -at- MEGA -dot- COM>]

Shannon wrote: We have to pay for the conversion from IBM BookManager to

     Framemaker by "virtual page".

I understand it's not a physical paper problem (tiny print?). In this
case, I'd rather evoke the number of words; it's that which counts when
we have to price the future cost of a translation. (There are other
facts to take into account, but that's the main basis.)
If your documentation is accurate and not wordy, reducing its size will
be rather difficult.
My practice:
1) Track the useless sentencing
Example (an actual one): //Chapter name: Description of the Functions//
The purpose of this function is to create a file >> Creates a file
Possible error messages are >> Error messages
There are several parameters >> Parameters //Comment: the number of
parameters may be useful, but it's a high maintenance information, and
if the initial example is correct, isn't very useful. Plus you can use
an automated numbered list.
2) Track useless unmaintainable info provided (junked) by the hot-line.
"Why did you put that thing in the documentation?" If the answer is 'I
was asked about this a few times', try to know if 'a few' actually is
'more than once, eeeer, at least twice',  then the answer is 'Keep it
safely in YOUR drawer and get ready to fax it when asked'. It's only
noise for other users.
3) The error message part often is a pleasure for text eradication
(shouldn't say that, with CNN on in the other room // no, I'm not at
work.). I once got rid of 120 pages which were to be maintained and
translated. The basic info they included was: "This cell has no comment.
Explanation: each cell should have a comment". Thanx a lot. That's (This
cell has no comment ) was on screen. It is now a 10 page thing where
only tricky messages are documented (if an error message is not
self-explanating, it must be modified, or the display thing enlarged
//E4521 meaning "No paper left in the 1st drawer, add some", or stated
"Add Legal in Drwr 1" need combing. This can take some time// ). The
only complaint came from of the developer who whined that he had spent
much time on this. (Shouldn't have, and it was paid time, and I'd love
to automate that with a vb thing. I and the translators are deeply
annoyed with that silly stuff, as much as users, and removing it reduces
our costs, //preserves the Amazonia - no, pleeeeze no threading on that,
pollution due to paper production mostly involves water//, and thus may
result in a raise in your -salary, stock things, ...)
4) Old rat pages that explain tricky situations due to a very specific
client.
Go to the client management department, then ask 'How many clients are
concerned'. The answer will be 'Oh, there are.' Then ask 'How many?
Could you check?'. The answer may be 'Yes, there WAS that one, but we've
not heard about that company for years'.
5) Pages kept because they are there, such as (I removed them)
flowcharts that explain the files in input and the files in output on a
'years ago on a mainframe but now PC only' software, whilst users can
see the file names and extension (hopefully, since they must enter
these)
6) Lengthy lists that should be replaced by 'If you wish to see the list
of XXX provided, use the Print List function /File>Print list or
F154257'. (There are a few left around in our docs, such as a 15 page
word style list, but that's easy to create and a pain to
maintaintranslatecheck information that nobony seems to use anyhow
//they -people in charge of creating doc templates- override these
styles each time they can't find the proper one and just say 'oh, i
didn't notice there was something about it in the doc, then politely
have a glance, and dump the whole thing//; could the users that read it
and find it useful send a portrait?)
HIWU
"Le rouge est une couleur proche du bleu, mais pas trop" P. Desproges
Gilles CASSIN
mailto:gcassin -at- mega -dot- com
+33 1 42 75 40 22
My opinions are mine, and neither you nor my company can take credit for
them. YOU can cite them if you think they were of use.

 From ??? -at- ??? Sun Jan 00 00:00:00 0000=