Writing the same manual twice (very long)

["S.North" <north -at- HGL -dot- SIGNAAL -dot- NL>]

Unclassified

I'm posting this to the list because it *might* be of interest to several
people.

While I cannot formalise any general rules immediately, by recounting three
experiences with different employers I hope to be able to abstract them for
you.

The first was about eight years ago with Philips where I was responsible for
writing/producing all the manuals for the optical spectrometry division.
After an initial period of instability, marketting settled on one consistent
line of products. It consisted of some 16 different spectrometers, one for
each method of exciting the source material to give off the light needed for
analysis. However, 95% of the mechanical and electronic components were common
to the whole range - with a small complication that there were a few versions
of the power supply to accommodate different power outputs. Needless to say,
the installation (and pre-installation since a lot of site preparation was
needed to prepare for delivery of the equipment) instructions were completely
different, and hence these were not a problem.

I first (since at this stage we weren't told that there was to be a whole
range of spectrometers) attempted to keep up with individual manuals for each
version. While there were only two or three this wasn't too much of a problem
other than causing a lot of cut and paste work and meaning I had to keep a lot
of personal records to keep track of my progress. I very quickly (by the time
the fifth model was announced) realised that this was just *not* going to work.
The only solution I could think of at the time (I have since learnt how to do
a lot with databases through working on the engineering proposal documentation
for space station Freedom when I worked at the European Space Agency some
years later, but that is a different story ...) was to completely re-write the
existing manuals (I had to re-write since I had inherited the original manual
and its structure would not permit me to do what I thought necessary) and
organise them into modules. Each module then became a chapter. For example,
there was one (common) chapter on the theory of optical emission spectrometry,
another (in three versions) for the power supply, etc., etc. Working with
chapters as modules worked, provided that you were *very* consistent with you
terminology (the formulation of model names had, for example, to be very
consistent to allow me to perform global search and replace actions). It was a
bit clumsy in that some manuals had up to 26 individual chapters but that was
something we all seemed to be able to live with.

As the writing department grew (there were only two of us at first), so did
the manuals as more information was identified for inclusion. The one thing
that nearly threw the system was the parts lists. We ended up with a complete
illustrated parts list consisting of exploded view line drawings and complete
lists of component identifications. I could not separate this out into modules
very easily since the artist's ideas of the construction were very different
from ours. It was a long struggle to persuade the technical drawing department
of what we needed but eventually we had a lot of drawings re-done to remove
specific version detail and allow us to approach the equipment at the same
level of abstraction.

One thing that was missing, which I discovered to my cost later, was that the
system was far too dependent on what *I* remembered. My excuse is overwork (at
the time I was also doing laboratory automation documentation, x-ray
scintillation spectrometry and x-ray diffraction equipment, as well as power
sample fusion equipment - as well as instructing and providing engineering
support in the field - I actually had to *use* my own manuals!). While I was
the only one writing the manuals I could keep track of what and where. I left
to go to a 'better job' and had to handover my work to someone else. Within
the space of about three weeks I had to write a complete set of design
documentation for the manuals, explaining all these things. Not easy in
retrospect.

My second example is more recent, some five years ago (but I am still working
on the material so I can say a bit more about the end results). We (Signaal)
have a so-called 'virtual machine' environment. Basically, without saying
anything I'm not allowed to, it is a sort of imaginary computer operating
system composed of 'logical objects' that an application programmer can
manipulate in his code. It has three interfaces; one in Ada, one in C, and one
interactive CLI (command line interface). Each of the interfaces is written by
a completely separate programming team (and the C programmers do not know Ada
and vice versa).

trying to capitalise on my previous experience, I sat down and spent a couple
of months (!) trying to piece together a sort of 'documentation philosophy'.
The end result was 14 different manuals (one introduction manual, two
programmers manual, three software control and monitoring manuals, one test
monitor manual, one I/O manual, one instantiation, one performance
manual, one test environment manual, etc.) based on a wide range of user
information needs. This sounds a lot, and can be a little unwieldy, but it
does work. Some readers, for example, only program within the environment
while others construct systems; some write device drivers to operate under the
environment, and a (select) few have to install the software.

Each manual is, as before, split into modular chapters, and it appears to work
(I have been constantly updating and expending the manuals over the past four
years without any real problems).

The design documentation I wrote has been an invaluable assistance, and I
would suggest that it is *essential*. When a new function or facility is added
(during which time I may have been 'away' from the manuals for over a year) I
have to first identify who needs it (which manual). Then I need to identify
what level, what tone, what style of presentation, and weld it into the
existing material so that you can't see the seams. The design philosophy helps
me retrace my thoughts and, sometimes, defend what might at first seem to be
an illogical decision (the staff of the various programming teams has now
turned over twice so that few of the original members are still working on the
project). I still have the odd uphill struggle trying to keep the interfaces
consistent (just because the C programmers think of a 'nice' new function
doesn't mean that the Ada team will agree, and sometimes a C function cannot
even be implemented in Ada). I have even had to lose a few 'battles' meaning
the inclusion of 'pseudo' functions (i.e. non-existent) in C to map functions
in the Ada interface that aren't needed in the C interface because of the
additional facilities the language provides (such as record structures). I
really *hate* the idea of entries in the lists of contents and indexes that
point to information, while the page itself says "there is no information",
but this has been a practical compromise. Our review system works on 'peer
review' where we all sit round the table while an invited audience of
developers and users picks holes in the manuals. It isn't a very popular
activity and so I try to keep it as short as possible. When we can we review
several manuals at the same time. Doing the C and Ada manuals at the same time
helps to expose inconsistencies in the interfaces themselves, but the team
likes to do a comparison on a page-by-page basis. My argument against this
(other than the above) is that no-one programs in more than one language and
therefore the C programmer is not at all interested in what happens in Ada,
but I have had to live with it.

Again, I keep common what I can, and terminology is even more of a concern.

The third, and final example, was an executive information system that I
helped document on a freelance basis. This package runs on Mac, but they were
busy porting to Unix and there should be an MS-Windows version *real soon*.
Since this is much 'lower level' documentation, and predominantly screen
oriented, the problems have been a little different. The structure and workings
of the three programs are almost identical, but all the screens are different.
We have overcome this in much the same way, by modularisation, but the
illustrations are kept separate. My controlling the illustrations (uniquely
identifying each one) and attaching any specific text to it (like descriptions
of the buttons, colours, etc.) we have a central 'core' into which the
platform-specific parts can be 'poured'.

I now work in software as a quality assurance consultant, but I remain a
technical author (we average about a page of documentation for each line of
source code - and on a project of 20 000 000 lines of source code that's a
*lot* of documentation) and, the more I learn about software engineering (even
after 22 years in software I'm *still* learning!) the more similarities I
find. For multiple versions of manuals many of the same concerns seems to
apply that are valid within modular programming and software re-use, namely:

. make a design and document it
. record how the design has been translated into manual(s)
. locally encapsulate any information that is likely to change (keep it within
  well-defined boundaries) and ensure that if it has any knock-on effect that
  this is recorded somewhere (someone else may have to work on the manuals).
. abstract (move to common parts) wherever you can
. be *extremely* consistent, even at the risk of being boring
. record changes, and analyse each one to assess its' effect on other parts

Hope this helps.

================================ Unclassified ==================================
Simon JJ North BA EngTech FISTC                 Consultant, Communication of
north -at- hgl -dot- signaal -dot- nl                            Technical Information
Tel: (+31)-(0)74-483533 (work)                  Quality Group
     (+31)-(0)5490-28623 (home)                 Software Research & Development
--------------------------------                Hollandse Signaalapparaten BV
The opinions expressed do not                   PO Box 42, 7550 GD  Hengelo
represent those of my employer.                 The Netherlands.
================================ Unclassified ==================================