Re: Recognition at last!

[Chuck Melikian <chuckm -at- MDHOST -dot- CSE -dot- TEK -dot- COM>]

Micheal Wing wrote:

# I guess it is easy to gloat at the documentation and think that we can
# outdo the giant (in this case MicroSoft).  Is it faulty Technical
# Writers or is it the constraints under which they must work?  Given the
# same parameters in which to work, how many of us would do better?

I think in the case of Microsoft it is the constraints under which they
work. Several years ago, Microsoft came to the Portland Macintosh
User Group monthly meeting to present Word 4.0. Interestingly, Microsoft
sent members of the documentation team to present Word - no Marketing
droids. I spent a while talking to the project team editor about
the problems I had with their documentation. She told me an interesting
story.

It seems that as soon as Microsoft shipped Word 3.0, they started
getting lots of complaints about the documentation (I have a theory
that any version of Microsoft Word evenly divisible by 3 will be
a major disappointment ;-) ). The writing team spent a lot of time
reviewing the customer complaints and developing a plan to improve the
documentation for version 4.0. Their plan estimated one year to completely
rewrite the documentation to address the problems the customers had
complained about. They put together a presentation. *Bill* showed
up. Bill said NYET! Bill said "You got six months."

The moral of the story? What the writers want to do and what management
will let them do are not the same. I didn't get the impression from
talking to the writers that they were particularly dim. They didn't
have an arrogant attitude toward their customers. They wanted to do the
best job they could.

# I, personally, would need some questions answered before I passing
# judgment on Microsoft's writers.  Some of the questions are as follows:

# What is the ratio of writers to programmers?

# How much lag time is there between Developer's code freeze and
# documentation's deadline?

# What was the state of each piece of functionality at the time it was
# documented?  How much changed since it was last worked on?  Was there
# sufficient time to update the document?

Based on what I heard from the writers that came to the PMUG meeting,
their biggest driver was how long they were given to update the manuals.
For those that remember (Arlen?) Word 3.0 on the Mac was at least as
buggy as Word 6.0. I don't think Bill gave the programmers enough
time to complete their job either. I suspect the time between
code freeze and product shipment was too short for both the writers
and the programmers.

# Idealistically, no document should go out until every instruction is
# verified and tested, every "i" is dotted, every "t" is crossed, and so
# forth.  In an ideal world, documentation is given ample time to finish
# AFTER code is complete and GUI design is frozen.  In reality, this
# doesn't happen.  If a company waits for every tweak, it loses time to
# market.  Therefore, compromises are made and some losses are deemed
# acceptable.

On the Macintosh, Word holds about the same percentage of the word
processing market as Windows holds of the PC market overall. Competitive
pressure on the Mac (for Word or Excel) is essentially non-existent.

Let's face it, writers are like engineers, we can always find ways
to add to our product. :-)

# This would not be the case if each company was regulated so that they
# could not release a product until every function and documentation of
# that function was tested and verified.  But that's not the case.  If
# your competition is going to ship and has accepted a policy of
# "allowable defects", it is extremely hard to say "I will serve no wine
# (or software, or document) before its time".  Therefore, it's a Mexican
# standoff.

I think it is more likely a question of what will the customer accept.
Low quality products are made because there is a market for them. If
Microsoft's sales dropped 90% after they shipped a buggy program because
customers switched to WordPerfect, Microsoft would get the point. But that
doesn't happen. People don't switch to WordPerfect, they just don't
buy the upgrade for Word. Word's market share doesn't really change.
Microsoft just figures they will pick up the sales with the next
version of Word (or Excel or PowerPoint or whatever).

# It bothers the artist in all of us (Writers, Programmers, Draftsmen, and
# so forth) to ship something less than perfect.  However, it seems that
# many customers go with who can get to them first instead of who can get
# it to them best.  Often, the vendor will work feverishly on an upgrade
# -- but the hook (first product ship) must be in place.

# Again, I don't know the constraints under which Microsoft Technical
# Writers work.  But if is like most of the software industry, everyone
# puts in extra hours, handles multiple tasks while learning new tools,
# and documents functionality that at the time of documentation is still
# theoretical and subject to change.  Some may gloat at being able to
# outdo the giant (at least saying they can by imagining doing the task
# under their personal constraints), but I remind myself, "somehow they
# have become a giant".

It wasn't because of their manuals. :-) I think Microsoft got lucky.
I am not saying they didn't do good work; just that there were a lot of
other people doing good work too and they didn't come to dominate the
market. It is important to remember this if you are looking for someone
to emulate. Some of the early Balloon help in Word (on the Mac) was astoundly
pointless. The original Balloon help for the File menu in Word said that
the File menu was used to open and save documents. Duh! I think anyone
with two brain cells to rub together could have figured that out by
reading Open and Save on the File menu! The Balloon help didn't say
anything about the page setup or printing options that were available
in the File menu. I suspect that whoever wrote the Balloon help for
Word was probably given two weeks to do it all. It wasn't wrong, it just
wasn't useful. I am far more influenced by good writing than I am by the
bestseller list. I'll bet that Harlequin romance novels outsell "literature"
novels 100 to 1. I still prefer to read literature.

I agree with Michael, it is easy to knock the documentation that someone
else writes if we don't look below the surface. It may be that, given
the constraints the writers at Microsoft work under, they are doing
spectacular work. Given my experience talking to some of their writers,
that seems more likely to me that the scenario that they are all just of
bunch of chimps sitting around banging on typewriters.

Chuck Melikian
World Wide Customer Communications
Tektronix, Inc.