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

[Glenda Jeffrey <jeffrey -at- HKS -dot- COM>]

Frank Watson (watson -at- nene -dot- cms-stl -dot- com) wrote:
: THE FEASIBILITY OF USING USER DOCUMENTATION AS PRODUCT
: SPECIFICATIONS:
: A Summary of a Discussion on the Techwr-l Listserv...

: ...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.
: ...The idea has a lot of merit... [so] why am I now telling
: you that this is a BAD approach? Because the biggest issue is:
: Who becomes the author?

Great summary! I somewhat agree with John Bell's assessment that you
have to be careful where you insert tech writers in the process when
they are not fully qualified to design the interface. However, I am
surprised that nobody mentioned the role of usability testing in
developing specifications and user documentation. Our company does
things this way:

1) Developer/designer writes specifications that explain the
   (draft) user interface and the functionality.

2) Tech writer writes high-level conceptual documentation
   and points out any conceptual flaws.

3) Developer/designer conducts several levels of low-fidelity
   usability testing (using paper mockups). The technical writer
   is usually involved in the later tests, once the UI is a little
   firmer.

4) Tech writer writes detailed procedural documentation and help.

5) Developer codes the UI and functionality.

6) Tech writer checks that what got implemented is really what was
   spec'ed and documented.

Doing things this way seems to work well for us. We don't feel the
need to get in on the "ground floor" in step 1 -- we would just end up
getting into "opinion wars" with the developers. We find it works much
better to let the usability tests reveal the "truth" -- that is, what
does the *user* find easy to learn and use?

If we think that there are still UI problems after usability testing
is done (or even during testing), then we speak up; we are even free
to propose our own usability tests to reveal flaws not shown by the
developers' tests. In any case, because most of the tests are done
using paper mockups, it's no big deal for us to come in with criticism
near the end of the process, since very little coding effort has been
expended at that point.

Is anybody else using a similar process?
--
Glenda Jeffrey                                     Email: jeffrey -at- hks -dot- com
Hibbitt, Karlsson & Sorensen, Inc                  Phone: 401-727-4200
1080 Main St.                                      Fax:   401-727-4208
Pawtucket, RI 02860                                Web:   http://www.hks.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-