Was: How much documentation for 1000 hours

Subject: Was: How much documentation for 1000 hours
From: Mary Deaton <knowware -at- MSN -dot- COM>
Date: Fri, 29 Mar 1996 20:05:45 UT

Not effective for whom? I think they are finding it is highly effective for
the vast majority of their users. The people who complain are highly
sophisticated users with a background in Windows 3.1 and who are trying to do
stuff most users do not typically do.

They have documented what 80% of their users need to do 80% of the time. The
system would be far more difficult to use for the vast majority of Windows 95
users if it had hundreds of more detailed reference topics in it. I think it
is correct to ship detailed reference material separately for only those who
need it.

They know the WIndows 95 Help system have some limitations. Gayle Picken, the
lead for the project, will tell you it was a mistake to take the Help buttons
out of dialog boxes and not provide overview topics for them. I think they
could have used a few more definitions within topics, and in some places
provided a little more background in a concept or overview topic accessed via
Related Topics. I wish there were more troubleshooting topics, or that Windows
95 Help had AnswerWizards, as Office 95 does. But I am sure the last was a
question of being able to meet the ship date.

You can see a similar model in Office 95 in which topics are more detailed and
reference information is provided, but a productivity application is not an OS
and people need different levels of information in each situation.

And with the access Microsoft now gives end-users to their product support
knowledge bases--CompuServe, their Web pages, MSN--I find it fairly easy and
inexpensive to get detailed information on a particular problem without having
to buy any third-party book at all.

Also, I don't think we can ignore cost-effectiveness as a factor in the
documentation we produce. Is it useful to the user to produce expensive books
whose cost is reflected in higher software costs when most users do not need
most of the information most of the time? Or to consume a user's hard disk
with topics they never read?

Granted, the so-called "minimalist" model does not work for all people all of
the time. Careful audience analysis is the only thing that will help you
decide how to adapt any model to your own needs. My point was that you should
not schedule documentation projects based on how many hours it takes to
program the software you are documenting. User needs should be the determining
factor.

Mary Deaton

----------
From: Starr, Mike
Sent: Friday, March 29, 1996 9:21 AM
To: Mary Deaton
Subject: RE: How much documentation for 1000 hou


Mary:

I think one of your basic premises is faulty. I don't believe the
end-user documentation provided by Microsoft with Windows 95 is highly
effective. It might be highly cost-effective, but I don't believe that it
is anywhere near as thorough as it should be. The Microsoft strategy of
giving the end user token documentation with the product then selling at
a premium the real, thorough documentation works for them because they
have a captive audience. In competitive situations, the documentation
needs to far better.

I will, however, agree with your premise that the better designed a
software product is, the easier it is to document. I've been involved in
some documentation projects where the software was so poorly designed
that it was a real nightmare to document (six or seven layers of nested
dialog boxes, etc.).

Mike

----------
From: Mary Deaton[SMTP:knowware -at- MSN -dot- COM]
Sent: Friday, March 29, 1996 10:42 AM
To: Multiple recipients of list TEC
Subject: Re: How much documentation for 1000 hou

I'm a little distressed at the answers one poster is getting to whether
you
can estimate documentation time needed based on hours of programming
done.

Nowhere in the responses I have seen so far has anyone addressed an
approach
that says how you decide what your end user needs to have documented and
how
long it will take to produce what the end user needs. Windows 95 is a
highly
complex product that took several years to develop. It's end user
documentation is contained in a book of less than 100 pages and a Help of
less
than 1 meg. The time it took to accomplish the documentation was based
not on
how many hours of programming time went into Windows 95, but how many
hours of
the documentation groups time was needed to design and produce highly
effective documentation. In their case, it included designing and
building a
new Help engine, of course, but they did that in order to produce more
effective documentation.

In my experience, the more hours spent programming, the less I may need
to
document--the program is well-designed with a highly intuitive interface
and
workflow that does not require me to make up for its deficiencies. On the
other hand, I have worked on programs done with no thought for interface
design which were literally slapped together in a couple of months, and
it has
taken twice that long to write the docs because it takes forever to
figure out
how the damn thing is supposed to work.

Now, I'm talking end-user docs here. System documentation may bear a
closer
relationship to the number of hours spent developing the system. But for
end-user docs, it is irrelevant to me how long it takes them to develop
it.

My starting point is what tasks will the user be doing using this piece
of
software, what do they already know about either the task or the use of
software to do it, how can I best support them in doing these tasks
quickly
and accurately, and what amount of time do I need to accomplish this?
Those
are the questions you need to ask when you want to know how to schedule a
documentation project.

Mary Deaton


Previous by Author: Re: How much documentation for 1000 hours of programming?
Next by Author: Re: Internet or library
Previous by Thread: Job Listing - LA and San Diego
Next by Thread: Passive/active voice in int'l documents


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


Sponsored Ads