Summary: User Docs As Specs (Long - but Worthwhile)

[Frank Watson <watson -at- NENE -dot- CMS-STL -dot- COM>]

THE FEASIBILITY OF USING USER DOCUMENTATION AS PRODUCT
SPECIFICATIONS:
A Summary of a Discussion on the Techwr-l Listserv

I recently asked members of this list for feedback about first
writing user documentation for a product and basing the
specifications upon the user documentation.  I received 15 responses
- not as many as I would have thought, but all thoughtful and
informative.

I wrote:  "The intent will be to develop a draft of the user
documentation first, which will become the specifications around
which the software engineers will develop functionality and user
interfaces.  Have any of you had experience with this approach?
What have been the advantages and disadvantages?  Problems?  Success
stories?  Any suggestions about how to best implement this approach?"

I'm not sure about the accepted protocol of summarizing information
of this type.  I will use the names of those responding, except for
the one individual who asked that the name not be used.  A summary
of the responses are provided below.

NUMBER OF RESPONSES

Six persons said they had used this approach, going back to the
1980s.  The efforts were generally successful.  A company mentioned
several times is Mathematica, which I have not had time to try and
contact.

SUCCESS STORIES (AND RELATED PROBLEMS)

Ann Weiler (annew -at- chancery -dot- com) shared the following experiences:

"I found it worked well and the programmer found it worked well. We
had detailed functional specs, but instead of high level design, we
used the manual. Also, the user interface was designed by a team
consisting of the project manager, programmer, QA, and me (the
writer). It took a while, but the result was that by the time the UI
was finalized in the manual and sent around for review, there were
very few changes.  One problem was that my manager didn't realize
exactly how the project was being done and was quite surprised to
find me without much to do near the end when she thought (from past
experience) that I should be pulling all-nighters. I haven't worked
like this since. Lately I've been writing from software prototypes
and high-level design.

"An interesting aside: The company ran into some difficulties, and
laid off the programmer about 2 weeks before the product was due to
ship. He went back to his desk and destroyed the source code and any
backups. The company had to completely recreate the software based
on what the manual said it would do!"

George Hayhoe (gfhayhoe -at- scescape -dot- net) passed along this information:

"'I've done this several times. I attended the preliminary design
meetings of the development team, got an idea of what they wanted the
product to do, and then drafted a user's guide based on my
understanding of the new product's features and my best guesses of
how the developers would implement them (the latter based on my
experience documenting previous products the team had developed).

"What you wind up with is a prototype manual. It's got lots of holes
in it, and it bears only passing resemblance to the user's guide for
the 'as-built' product. But the developers and their customers (I
was working for an organization that built software for internal
corporate users) found these manuals particularly useful--especially
the customers. The prototype user's guide made the proposed product
much more real to them than traditional design specifications.

"I'll also add that the projects on which we used the prototype
manual for product specs were (except for one miserable failure
resulting from internal politics, unrelated to the software being
built) generally much more successful than usual, with the products
being developed more quickly and adopted by customers more
enthusiastically than the usual project."

A writer who asked that her name not be used said:

"I think it's a good idea; we tried this approach in the mid-80s
where I used to work.  We wrote 'reference documentation' (pick this
option, this menu appears, etc.) to be a design spec (or, at least,
the user interface spec). After the software existed, we wrote "user
documentation" (here's an example of how to perform this task, etc.)
'Reference documentation' and 'user documentation' are terminology -
others might call them by different names, but it's the concepts
that are important.

"Pros and cons:

"1.  As design becomes reality, design gets modified - therefore,
the reference doc constantly changed.  In a gov't environment, that
necessitated lots of paper 'change pages' and writer frustration. In
the real world, it shouldn't have to be as painful - just rev the
whole document.

"2.  It involved the writers *up front* in design, which helped us
tremendously in understanding the software and its purpose."

WRITERS - KNOW YOUR LIMITATIONS

Several respondents praised the idea, but cautioned writers to be
aware of their limitations in the specification-development cycle.

For example, Peter Ring (prc -at- pip -dot- dknet -dot- dk) suggested that such user
documentation as specifications must "be done by market/user
oriented people with power plus technology and market knowledge to
strike back when R&D says 'Impossible!'"

Beth Staats (bstaats -at- artisoft -dot-  com said that at her company, "they
need the specs faster than we can write the docs.  They write them
in engineer-ese, throwing in all the technical stuff they need to
know.  Those specs are for developers' use only.  If they needed
specs to show the company big shots what the product will do, they'd
probably ask us to write them.  Currently, they're using product
managers' brief descriptions of the functionality for that purpose."

Karen Otto (karen_otto -at- hp-spokane-om2 -dot- om -dot- hp -dot- com) took a wider view
of the problem:

"I think your company is trying to do the right thing, but they seem
to have missed the point.  Meeting the users' needs is the paramount
objective. The documentation and the rest of the product are merely
tools to achieve that objective.  Where you really need to start is
with the user identification, and work with developers and
marketeers to create a list of the users needs.  From that, you can
evaluate what the requirements are for documentation, HW, SW, and
other parts of the product.  Finally, you will have to evaluate
which of these needs you can actually fulfill, given your resource
restrictions. Then you have a useful product specification. You can
also easily derive priorities for features from this specification.
Maybe you can influence the product development cycle by presenting
the users' needs in place of the documentation outline as the
starting point."

Len Olszewski (saslpo -at- unx -dot- sas -dot- com) elaborated on Karen Otto's
comments.  "Using user documentation as a product spec is better
than not having any specifications at all," he said.  "However there
are other things besides what the users see that good software
developers need to consider in the analysis and design stages of a
project. You might get away with using user documentation as a
functional requirements specification. But full requirements,
design, and testing specs don't usually fall out of what the end
user gets as product doc.  Software developers should try to meet
the needs of their customers, no question about that. But they do
them and their company a disservice if the code they provide looks
functionally correct, but is not solid underneath the sheets."

ONE FINAL CAUTION

Citing a similar concern - about the lack of technical qualifications
on the part of the writer - John Bell (jbell -at- tele-tv -dot- com) provided
the following ideas:

"The idea of writing the user's guide first and then making the
software to match it has been mentioned many times. I even had that
idea 12 years ago when I was about to embark on my own software
project.

"The idea has a lot of merit. The pluses are:

     * A customer-oriented approach

     * A higher probability of a logical flow

     * Everyone gets a solid idea of what the product is expected to do

"With benefits such as these, why am I now telling you that this is
a BAD approach? Because the biggest issue is: Who becomes the
author?

"That approach is really a high-level design specification (HLDS). An
HLDS should be written by a software designer, not a technical
writer. In large companies that have the time and money to do it
right, the software designer consults clients, tech support, tech
writers, trainers, and so on. The tech writer usually helps the
software designer with the text, layout, and formatting of the HLDS
(and other specs), contributing about 30% of the project's total
effort.

"The HLDS states what the product is intended to do, and may provide
some hints as to the general algorithms to be used. Its purpose is
to show to management, clients, and marketing so that everyone has a
solid idea of what you're going to produce. When management blesses
it, you proceed to the next step.

"A detailed design spec (DDS) is the next step. It sets out the
details of algorithms, data structures, global variables, and other
stuff. Usually the software designer writes this with the help of a
few of the sharper programmers. The tech writer's involvement is
usually just spell-check, grammar, format, and layout. The DDS is
usually for INTERNAL use only, only the pushiest clients ever get to
see it.

"If you get the job of writing the draft user's guide which the
programmers will then follow, you in effect become the software
designer. You may or may not be qualified for this job, and if it
fails, who will they point fingers at?

"By the way, in my management career I had only one writer who worked
on a project where they did REAL specs from beginning to end
(business requirements, technical requirements, high-level
functional specs, detailed functional specs, high-level design
specs, detailed design specs, data dictionary, interface control
documents, and installation specs). She reported that the HLDS formed
about 75% of her finished User's Guide. She just had to extract the
information and put it into more of a User's Guide form.

"In an ideal world each of the documents I listed in the previous
paragraph feeds into the next. At each step you add information to
the existing document. Thus the incremental effort of going from one
to another is not horrendous. Also in an ideal world the detailed
design document is a magic document. You hand it to the following
groups:

     * software developers

     * tech writers

     * trainers

     * testers

Each of these groups takes the DDS and goes off to do their magic.
They meet back when they are done. If the DDS is **GREAT** then the
user's guide should be 95+% percent accurate. So should the training
material and the test plan. The developers will have made a few
deviations from the DDS just because there are always some things you
discover you cannot implement exactly as designed. When the groups
meet, the developers pass over the info of what they did DIFFERENTLY
than the DDS. (Of course, they could pass the info incrementally as
it happens, but you still need a meeting at the end to consolidate
everything.) Everyone takes that info and adjusts their products. The
User's Guide, the Training Guide, and the software should all go into
testing together. Testing needs to look at ALL aspects of a product,
not just the software.

"I think your company has the seeds of the right idea: put it in
writing before you code. This is designing. You need a plan before
you attempt to build. I think that making the draft user's guide th e
design is making the writer a software designer. If the existing
designers take on the task of writing this 'design' then you get a
user's guide that will be more like a spec than a user's guide.

"I think the solution is for you and the software designer to
cooperate and produce an HLDS. You act as user advocate and push for
task-oriented design, sensible labels for fields, menus, windows,
and so on. The software developer's role is to make sure the design
is something that can be implemented in a cost-effective manner. The
designer should hold the final decision making power."

OTHER RESOURCES

One respondent noted that a workshop about this approach was
presented a few years ago by JoAnn Hackos.  (No contact
information.)

A book, HOW TO WRITE USABLE USER DOCUMENTATION by Edmond H. Weiss
(no publication information included) was also cited.

INVITATION FOR ADDITIONAL FEEDBACK

This could be of tremendous interest to many tech writers and their
managers.  It could be worthwhile if this summary sparks a renewed
thread on this topic on this list.

If nobody objects, I am considering looking around for a possible
"real" publication for this summary or a variation of it.

Thanks for all your feedback!
-Frank Watson-
watson -at- cms-stl -dot- com

                  TECHWR-L List Information
To send a message about technical communication to 2500+ list readers,
E-mail to TECHWR-L -at- LISTSERV -dot- OKSTATE -dot- EDU -dot-  Send administrative commands
         ALL other questions or problems concerning the list
       should go to the listowner, Eric Ray, at ejray -at- ionet -dot- net -dot-