Re: Online Documentation. New! Improved!

[Robert Plamondon <robert -at- PLAMONDON -dot- COM>]

Mike writes:

>And my theory is that product development cycles have sped up (at least
>in software).  Many development tasks are no longer linear (first we
>develop this, then we develop that).  Instead, many pieces are developed
>simultaneously.  Furthermore, development may occur in multiple states
>or even multiple countries.

True.  The nonlineariety problem is made far worse than it absolutely must
be in many cases through what I consider to be a fundamental error in
management: that of committee design.

In most products that I've been associated with, the elements of the
product are parceled out to specialists in different field, as they
must be, but there is no person who is in actual overall control of
the product.  Typically, the marketer who was in nominal control has had
no authority, and in fact was too uncomfortable with most of the
specialties to assert what authority he had.  The result was an
incohesive, somewhat randomly targeted product.

Even very large projects can be directed by a single person.  A
classic example would be the movie STAR WARS, which was an enormous
undertaking that involved filming on three continents, an entirely
new class of special effects, and the largest movie budget up to that
time.  Yet George Lucas was personally in control of the entire thing,
from the first-draft script to final film editing.

A more traditional example would be Kelly's Skunk Works at Lockheed,
which developed the most amazing airplanes of the 1950's.  While there
was a management fad in the last decade to emulate the Skunk Works,
(which I believe was set inside an enormous hangar with engineers,
draftsmen, and riveters all working in the same room, the better
to argue with each other and hammer out solutions when things started
to go wrong), I believe the most recent recreation left out Kelly, who
was certainly an important part of the picture.

But most projects I've been involved with in the last dozen years
had a group of engineers who wanted to meet their deadlines, but who
had little buy-in or even awareness of the needs of the customers
(or even the needs of other departments) or the nature of the competition.
When they made expedient choices that made the job of Production or Tech
Pubs or Sales or Marketing or the customer nearly impossible, they
were chided gently -- but that's all.

Of course, that's only really the case in the high-tech end of things,
where Technology is All.  (In the land of the buttless, the half-assed
man is king.)  Other industries have other dominant players.  But
the management problem of having the product converge properly ON
ALL FRONTS is universal, and requires either a "band of brothers"
development team or one with strong overall leadership to work
smoothly.  The other methods are all quite painful, though sometimes
the products turn out okay.

>Another complication is reusable code.  A new application may use
>functionality for which code already exists. For example, if the new
>product for which you are documenting is a terrain analysis application
>that also allows annotations, the code for the annotation functionality
>could be imported from another application.  This accelerates the
>development process.  However, if the documentation for the annotation
>functionality does not exist or cannot be easily extracted from the
>original application's documentation, the writer is already behind the
>pace.

Bad management again.  This problem happens when no one does even a
back-of-the-envelope analysis of what the project really requires.
It's not just a problem with documentation.  I have seen managers go
out and acquire logic designs that a cursory examination would have
revealed were neither testable nor manufacturable, and then spend
two or three times the cost of a ground-up design in an attempt
to salvage the expensive purchased garbage.  You would think that
people with management training on top of a technical education would
have the analysis skills to at least TEMPER their wishful thinking,
but this doesn't seem to be a reliable assumption.

Obviously, the requirements of integrating any newly acquired product
should be assessed at the outset.  Analyzing the work that needs to
be done and procuring the necessary resources to do it are basic
management tasks.  Being constantly hindered by deficiencies in this
regard means that managment has not learned its ABC's.

(Managers are not all bad, of course.  Such an assumption can cause you
a great deal of unnecessary pain.  One thing that we should all keep
firmly in mind when job-hunting is that we want to work for talented,
sympathetic managers who have something valuable to teach us.  I've seen far
too many people ready to cut their own throats under the influence of their
bumbling supervisors.  Seek out the good managers.)

>A third complication is flexible development resources.  Often some
>developers will be shifted from one project to another to meet current
>demands.  If a few developers are experts on raster data programming,
>they may be added to a project when raster functionality needs to be
>developed.  However, a new writer probably has not been added to the
>documentation end.

Management again.  If documentation is important to a project, its
needs cannot be ignored.  It can't be left out of the planning
process without courting disaster.

Neglecting documentation during the planning product is senseless.
You can't prioritize a list of things when every one of them absolutely
must be accomplished for the product to be successful.  Logically, no
essential task can be safely neglected.  Nowadays, documentation is
doubly important, because customers now expect products to be easy to use,
or at least easy to figure out after a few false starts.
If the product is so intuitive that this can be done without documentation,
fine.  Nuke the documentation. But if not, then the documentation is as
necessary as the core product itself.  It may be as unglamorous as
the Accounting department, but it's just as necessary.

>It appears to me that development has made changes to become flexible in
>their resources and accelerated their processes, but many Tech Doc
>groups are trying to tread water with slow-to-change (or rigid) document
>development techniques and guidelines.  (I'm referring to the medium in
>which a document is written and the tools and techniques for presenting
>that information not grammar and style).

>In earlier days you could document each stage of development as it
>progressed.  This provided time to concentrate on writing that one
>stage. Had there been online documentation at that time, you would see
>better examples of it today.  This is because there would have been more
>time to document and the online documentation technology would be a more
>mature technology.

>Time to market seems to be the major criteria for developing a product.
>If development time is accelerating, documentation time better
>accelerate.

But development ISN'T accelerating -- it's slowing dramatically.  Chuck
Peddle designed the 6502 microprocessor using manual methods.  It took
him something like six weeks.  The Pentium Pro took six zillion man-years
(and several calendar years) to design.  Yet the externally visible
complexity of the chip has not increased by the same proportion.  The
instruction set is longer, there are more pins, more registers, and
more timing waveforms, but the length of a data book containing the
same types of material is probably only ten times that of a first-
generation microprocessor, compared to (at a guess) a development
costs that was 10,000 times greater.

Major applications used to be dashed off by one to three programmers
in a few months to a year.  Operating systems used to be created as
unauthorized projects in people's spare time.  Microsoft Windows
was originally scheduled for launch in 1983 -- thirteen years ago.
The gap between Windows 3.0 and Windows 95 was five years, and many
people have dismissed Windows 95 as a pathetic half-measure to tide
people over until the masses are ready for NT (or vice versa).

Major projects like WordPerfect or Excel or FrameMaker only manage
a major update every two years. (Yet version 1.0 of these products
probably took less than a year to develop in all cases.)

So, no, I don't believe that things are moving faster.  I believe that
they are moving more poorly, because big projects are far more difficult
to orchestrate than little projects.  Management technique has not
kept up with increasing product complexity.

In a perfect world, Tech Pubs would be on easy street, because we
only document those parts of the product that are visible to the
user.  Most of the actual product complexity is completely hidden
from the user.  In fact, a lot of effort is expended to make
the product appear simple and easy to use, at the expense of increased
internal complexity.  So, in theory, the number of engineers per writer
should be going up, and writers should be able to go home right after
lunch on Friday.

It doesn't really work that way, of course.  Big projects are
a pain.

>No project manager or executive is going to be happy if
>product release is held back because of documentation!  Therefore, new
>technologies such as HTML documents, online manuals, online (context
>sensitive) help, multimedia CDs, and information mapping accelerate
>document development time.  They also allow for quicker documentation
>turn-around time (for updates) and allow the document to be finalized
>closer to the ship date (no print shop).  Furthermore, Marketing can
>instantly send out preliminary online documents to thousands of
>prospective customers.  Up-to-date revisions can be in a customer's
>hands in the time it takes them to download and replace the electronic
>files (an overnight print shop and federal Express cannot touch this!).

All of this is very nice, of course.  I certainly wouldn' t have filled
my office with workstations and PCs and their attendant software (or
is it the other way around?) if I didn't think it worthwhile.  But
in many cases the tools are neither here nor there, because the
environment is so screwed up that productive work is impossible under
any circumstances.

I remember two back-to-back projects I worked on,
one of which involved designing an advanced video accelerator with
an somewhate updated archictecture, and the other involved designing an
advanced CPU to be pin-compatible with an existing one.  The former
project was a nightmare for Tech Pubs, as the design changed daily,
design information was quite effectively (though unintentionally)
hidden from us (I recommend learning to use the same CAD software
the designers use in order to snoop on their work), and we spent a
great deal of time spinning our wheels and doing things over.  We
would have been finished at almost the same time had we taken a
six-month vacation at the start of the project.  The other project
was done to a fixed spec, so there were no suprises for us.  We started
very late, finished on time, and did the best work we ever did.  We
created usability studies for the manual and the upgrade CPU's installation
kit, demanded and obtained design changes in the installation tool,
and were thus partly responsible for a low return rate and high level
of customer satisfaction in a product whose status of "customer
installable" was open to question.

We had intended to do an installation video (on-line documentation
is a poor idea for a process that involves turning off your machine
and removing its CPU), but were shot down.  So its not like we never
considered using anything but paper.

Possibly more important than the fixed spec in the second project
was its fundamental nature as a "band-of-brothers" design effort.
The project was conceived by the engineering team, approval was
rammed through over the violent objections of some of the company's
upper management, and was thus done by a tiny group of truly committed
people (in various disciplines).  There was a tremendous level of
loyalty and commitment in this project, which was often absent in
projects that were decreed from on high without any preliminary effort
to sign up the workers.  We looked out for one another.  Nobody left
messes for anyone else to clean up without prior arrangement, because
we were all committed to launching a successful product in the marketplace.
It was fun!  Profitable, too.

>Because time, cost, efficiency, maintenance, and flexibility are major
>factors in producing documentation, a Technical Writer's may need to
>reevaluate their ascetics.

You mean 'aesthetics.'  We're only ascetics when they don't pay us
enough to adopt that high-living tech-writer lifestyle.

        -- Robert
--
Robert Plamondon, President/Managing Editor, High-Tech Technical Writing, Inc.
36475 Norton Creek Road * Blodgett * Oregon * 97326
robert -at- plamondon -dot- com * (541) 453-5841 * Fax: (541) 453-4139