Prototyping the Manual: SUMMARY

[Linda Sherman <linsherm -at- GTE -dot- NET>]

Many, many thanks to all who replied. Those of you who offered to send
me additional information, please do! Any help on this is very much
appreciated.

I had asked whether anyone had worked on a project where the user's
manual was developed before the rest of the design, and if so, whether
this had proved beneficial.

The responses broke down like this:

Total Responses: 13

Those with experience in this approach:      4
Those with experience in a similar approach: 1
  (A working GUI with no "backend" was protyped and partially
  documented for evaluation by potential customers)
Those with an opinion but no experience:     8
  (The opinions were very much appreciated, nevertheless!)

Those who felt the approach was useful:          7
Those who felt other approaches would be better: 3
Those who didn't express a clear opinion:        3

Interestingly, all 5 who had some experience with this approach were in
favor of it. The 3 who thought other approaches would work better had
never tried developing a prototype user's manual. I see two possible
interpretations:
  either (a) people on both sides of this issue are guilty of
             "my way is the best way" thinking,
      or (b) prototyping the user's manual really does have value

SPECIFICS
Many of the answers were very lengthy and detailed--thanks to those of
you who took the time to provide such thoughtful responses. It would be
impractical to repeat every detail here, so I will try to summarize the
responses:

1. Did it help the design/development process enough to be worth the
effort?

Among the five who had tried this approach, all felt it to be a net
plus, but to varying degrees, ranging from marginally beneficial to far
exceeding anyone's expectations.

Among those who had not tried it but had an opinion about it, three felt
to varying degrees that other methods would work as well or better, if
done properly, and one felt strongly that it ought to be done more often
than it is.

2. Did it include screen shots, menu layouts, etc. and if so, who
determined their content and appearance?

Most people said YES, but on one project the prototype did not include
screen shots or layouts in the prototype manual.

3. Was it reviewed by potential users/buyers? If so, to what extent were
their suggestions incorporated into the shipped product?

Two respondents were not certain whether the protype manual was shown to
users/buyers. The others said it was. Nobody said that it wasn't.

4. Was it revised lightly/moderately/heavily/not at all before it was
handed over to the developers?

The degree of revision varied considerably, with some saying it was
heavily revised, and some hardly at all. However, in retrospect, I feel
this question was poorly worded, as I can't imagine that anyone got the
manual exactly right on the first draft. I suspect the answers really
reflected the degree to which the design was thought out before someone
sat down to start writing the prototype manual.

One problem pointed out by one respondent was that users asked for some
features that couldn't be done. Whether this was for technical,
budgetary, or time constraints wasn't clear to me.

5. Was it integrated directly into the specification, or used mainly as
a basis for the specification?

Again, this varied. In a couple cases, the manual was virtually the
entire specification. In others, it was merely part of it or a basis for
it.

6. Was the prototype used as a basis for the shipped version of the
user's manual, or was the latter basically written from scratch?

Also considerable variation. In one case, the prototype manual was
shipped with the initial release of the product and the online help was
developed after release. Others had to alter the manual to some degree;
one threw it out and wrote a whole new one.

7. To what extent did the final product reflect the original concept as
expressed in the prototyped manual?

Answers ranged from "very little" to "almost exactly", but four out of
the five respondents said the correlation was 50% or higher.

8. Was the prototype manual used as marketing tool to generate interest
before the product was actually shipped? If so, how much effort was made
to make it look slick? And was it presented to prospects as "the" user
guide or as a draft version?

Two respondents specifically stated that the "prototype" manual was
written and designed with the idea of using it for marketing, that
special effort was put into making it look good, and that it was used
extensively to pre-market or pre-sell the product with great success. It
was clear that they didn't think of it as a prototype manual at all, but
as THE user's manual. Another respondent said it was used to "pacify"
in-house users. One used parts of the manual, but not all of it, for
pre-marketing.

ON THE ISSUE OF USER INTERFACE PROTOTYPING
A common theme in most of the responses, pro or con, was the
desirability of using some sort of prototyping software to design and
graphically document the GUI.

ANOTHER IMPORTANT POINT
One respondant reminded me that many software projects are undertaken
with nothing even close to adequate documentation. Her very good point
was that better to have the user's manual than nothing at all!

PERCEPTION = REALITY?
One respondant cautioned me to make sure the customers understand that
just because the manual is written doesn't mean the product exists, and
he gave a real-life example of this problem. Perhaps without realizing
it, I think he made a very strong case FOR developing a user's manual:
when customers and investors see a user's manual, they are more likely
to accept that this is thing is really going to happen than if you just
wave a spec sheet under their noses.

MY CONCLUSIONS
Based on the answers and some other informal research I've been doing,
I've concluded that writing the user's manual first can bring measurable
benefits to at least some software projects /*if*/ you do a proper job
of it. The specific benefits are:

1. It can replace a sizable portion of the formal technical
specification, if not all of it. If you have to write a user's manual
anyway, this can be an enormous productivity savings.

2. It provides an accessible means for everyone to agree on the user
interface and hardcopy outputs before any code is written.

3. It eliminates the problem of programmers trying to second-guess how
everybody else thinks the user interfaces should work.

4. It can be a powerful sales tool for attracting customers and
investors, especially if combined with a working demo of the GUI.

5. It can be used to generate in-house support for the product.

6. It is easier for users to understand than a formal specification.

7. Its existence is more likely to persuade customers and investors that
this product is going to happen for real and isn't just some
pie-in-the-sky idea.

8. The manual will be ready to ship when the product is. You won't be
caught in the all-too-common trap of having to ship an initial release
with inadequate documentation.

Thanks again to all who responded.

L.
--
Linda K. Sherman <linsherm -at- gte -dot- net>
Freelance Writer: Technical - Business - Government

 From ??? -at- ??? Sun Jan 00 00:00:00 0000=