Manual evaluation without metrics (Unclassified)

Subject: Manual evaluation without metrics (Unclassified)
From: "S.North" <north -at- HGL -dot- SIGNAAL -dot- NL>
Date: Thu, 22 Jul 1993 13:27:27 +0200

I hope no-one minds me submitting this to the list, but I thought that some
direct personal e-mail deserved a more 'public' reply (Hi Jon, I hope I can
help, but I will mail you separately if you want).

However, BE WARNED, this is very LONG and VERY OPINIONATED. I've got my
asbestos suit on. Flame away!

First of all 2 and a half cheers to DEC. Well done Mary Beth! Six years as a
helicopter avionics technician in the British Army sure taught me the worth of
laboratory tests. I have yet to see a laboratory that can simulate (and this
*is* genuine experience) standing on the engine servicing deck of a Lynx
helicopter at two o'clock in the morning. It's pitch dark, pouring with rain,
blowing a gale, and you are trying to change the alternator on the port
engine. You've got the manual balanced on top of the engine, and the toolbox
clampled between your knees to stop it sliding off the wet, oily, slippery
service platform. You are using one hand to hang on for dear life, the other
hand to wield a screwdriver, and the flashlight is in your mouth. You've
finally got the old alternator off, and the old one fitted - and *then* you
find out that you need a *special* torque spanner. It's about two miles back
to the hangar, but they can probably still hear you swear. Worse, by the time
you get back, you find out that the storeman (the only one with a tool store
key) has gone to bed! (that's fifteen miles away on the other side of Belfast
international airport). THEN you come to understand the need, as an author,
for listing any special tools FIRST..... I like to think that as a result of
that experience I became a very good writer of aircraft maintenance manuals
(my first job as a writer). You don't get the last half cheer, though. I will
*never* understand why VAX/VMS had to be so annoyingly inconsistent in its
use of command line qualifiers. IMHO, though, you *do* deserve an award for
VAX Document; one of the best uses ever found for TeX and one of the best
methods I have yet seen for enforcing a company-wide house style for
technical documents.

One major point of disagrement, though. I have tried reader's comments forms
with four different companies. Based on my experience, if you get *any*
response you are lucky. Basically, technical documentation is very much like
a smell - no-one pays any attention to it until it really starts to stink!
Besides, as any psychologist will tell you, it is extremely hard to formulate
questions in such a way that you do not pre-empt the answers. But, worst of all,
most comment forms and questionnaires suffer from the same fatal weakness as
checklists; namely, that you can only check on the things that you are already
aware of.

Mary talks about the way DEC do it, maybe I should explain the way we/I do it
(I used to have a team of three but with the recession and defense cuts I'm on
my own now).

Each product (software package), comes into the department as a set of
functional requirements that identify what the thing must be able to do. While
the software engineers are analysing these functions and translating them into
software requirements, I draft an information design document. This is
basically a plan for *all* the information that is to accompany the software.
This may be one or manuals, it may be on-line documentation, or it may be
training courses. IMHO, all of these methods have to be co-ordinated into ONE
information policy. At the same time I identify, and document, the types of
user and as much as I can about the user tasks.

As soon as the software design is underway, I can start on the actual manuals;
working from the specifications and (often) reading directly from the source
code as and when it is written (I don't advise this for machine code or
assembler!). This means that the initial users (alpha testers) can get a draft
manual *before* they get the software. After a while, they are invited to a
formal walkthrough and then a review when they get to complain about
everything.

We then go through a *long* process of iterative improvement, sometimes it can
be three or four years before I finally put a manual away on the shelf and
consider it 'finished'. Operating systems are like that (look at how many
versions of MS-DOS there have been!). Of course, I don't work on it
continuously, there may be a gap of about two years before I go back for an
update. This means, of course, that I do have to keep good records of not just
what I have done, but *why*. It means I have to *design* the documentation and
the information content itself. It also means I have to worry about a lot of
aspects that I don't normally pay any attention to for more commercial
projects (i.e. freelance work); I have to think of 'maintainablity',
'expandability', 'modularity', 're-use', configuration management and control,
version control, etc., etc. I even have to think about portability (try
writing a manual for a Macintosh package, and then find out that there will
also be an MS-Windows version *and* a Motif version...). Then you get to play
with the real *detail* problems - I write exclusively in English, but the
engineers I work with are Dutch, German and French, and my audience (current
products) are Greek, Turkish, Kuwaiti (and a few I can't mention). Not
simplified English (that supposes that you take English and then make it
simpler), no, S I M P L E English.

How do I evaluate? Well, I am lucky. For the first few months, or even years,
I am in fairly close contact with my readers. I can *see* them work with the
software. I invite comments (we have a formal readers comment system) but I
also keep in close contact with the help desk staff and find out where people
are having problems. For some software (such as FrameMaker) I provide the
first-line support myself (who knows the DTP software better than the technical
writers?).

I have always found it curious that so many American writers are female, while
their European counterparts are 99% male. American writers are 'language'
graduates, while European writers are normally technicians or engineers (I'm
safe, I graduated in French and English literature first and then had a full
training as an electronics technician). Why this came about I don't know. All I
do know is that in England it is strongly supported by the system. Not only does
a professional armed force provide a ready pool of experienced technicians
looking for a second career (most UK defence equipment is so out of date that
the knowledge is not readily transferrable to the civilian market), but
experienced technicians also readily gravitate to training positions and from
there to writing documentation. We expect our writers to understand the
technical
side. Not to the details of the product, but we do expect a mastery of the
basics
(like being able to read a circuit diagram). Why the difference?

[ BTW I still like to annoy so-called 'software' writers by asking them to
briefly explain the difference between an interpretor, a compiler and a
linker ;-} ... write software manuals, eh, how many languages can you program
in ??? ... ]

But I figure the market also gets what it deserves... I emigrated from England
to Holland because I was fed up with trying to compete with the 'second
careerers' I mentioned above (you have to leave the British army after either
18 or 22 years service - 36 to 40 years old, you get a nice pension and a
resettlement grant that's enough to *almost* pay for a house, so who needs a
well-paid job with promotion prospects?). They then get what they pay for ..
cheap, reliable, uninspired documentation written in compliance with VERY
strict standards.

A chicken-and-egg question for everyone ... which is easier, to teach a
technician to write, or to train a writer as a technician? America seems to
opt for the second, Europe for the first. (IMHO the first is probably better,
even if the writing isn't as good at least the technician mis-writes in the ways
that the technician will understand). After all, the best user's manual would be
written by the user him/herself: one user, one manual.

I don't know if they still do it, but IBM had great plans for making their
technical writers serve an apprenticeship with the sales organisation. I
thought that was a GREAT idea. When I was working for a certain well-known
Dutch electronics company I was asked to translate the French documentation
into English for a certain piece of third-party equipment. After a year I was
not only installing the thing all over Europe, I was also responsible for
training and was asked to join the design team for the next model. NOT that
I was that great ... (I thought so at the time, but I have since met several
other people who have had exactly the same experience). Basically, I think
the writer's job is to represent the user - which means s/he has to KNOW the
user, has to be as close to the user as possible and should, be able to work
at the same level as the user.

Software engineering has a notion of a "domain expert", someone who is an
expert in the field of application. His/her job is to advise the technical
experts about the "real world". Why doesn't technical documentation have the
same thing? Why isn't there an accountant, for example, employed as a
member of the documentation team for, say, Excel?

========== Translation's like a mistress; beautiful and unfaithful, ==========
========== or faithful and ugly .... ==========

Simon JJ North BA EngTech FISTC Quality Group, Software R&D
north -at- hgl -dot- signaal -dot- nl Hollandse Signaalapparaten BV

================================= Unclassified =================================


Previous by Author: Manual evaluation using metrics: Unclassified
Next by Author: LEVELS OF EDIT
Previous by Thread: Re: Job titles
Next by Thread: Re: Manual evaluation without metrics (Unclassified)


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


Sponsored Ads