Re: Recognition at last!

Subject: Re: Recognition at last!
From: "Wing, Michael J" <mjwing -at- INGR -dot- COM>
Date: Tue, 5 Nov 1996 12:20:15 -0600

>>As an intermediate-lever user trying to work my way up to power user, I
>>found the doc to be worthless. Give me back my REAL manual! And yes, I
>>have since purchased two third-party books. I had to.
>I think Microsoft is facing up to the reality that users will buy third
>party books anyway for user procedures because theirs have been so bad. I
>have seldom been able to figure out a way of doing anything halfway
>complicated from their manuals - even the more detailed versions. Their tech
>writers would be put to better use consulting on Wizards to guide users
>through tasks.

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, 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?

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

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

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".

In my opinion, we should strive for ideals but be driven by reality.
Ideally, I would like every iota of my document to be perfect before
shipment. In reality, I would rather do my part to get the product out
so that I will still have a job the next day where I can try to perfect
my documents.

Mike Wing

_/ Michael Wing
_/ Principal Technical Writer
_/ Infrastructure Technical Information Development
_/ Intergraph Corporation
_/ Huntsville, Alabama
_/ (205) 730-7250
_/ mjwing -at- ingr -dot- com

Previous by Author: Re: Query -- Software doc writer's responsibilities
Next by Author: Re: Help System See-Also loops
Previous by Thread: Re: Recognition at last!
Next by Thread: Re: Recognition at last!

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

Sponsored Ads