Use Case and the Importance of Storytelling in Technical Documentation

© 2010 Ugur Akinci
Software and hardware developers are well-educated intelligent engineers who usually have no difficulty at all in creating products. The real difficulty in product development is not the question of “how” (as in “how can we build this?”) but “what” (as in “what shall this product do?”).
Just like in screenwriting, the question “what’s this all about?” is the hard one to answer. Once that question is answered, the rest is up to the developers who usually deliver things as promised.
The “what” question is very important for documentation also since without a good answer, the technical communicator would not know what constitutes the “normal” behavior of the SW/HW system; that is, situations in which the interaction of the end-user with the system goes smoothly and the end-user’s expectations are met. The technical writer needs to know that scenario in order to write a good PROCEDURAL manual. To document the “typical” cases of “usage,” the writer needs to understand the “typical story” in which an end-user interacts with the system.
However, the writer needs to have an equally good understanding of the scenarios in which things break down and the user is frustrated as well. That is how a great TROUBLESHOOTING chapter is written. Without understanding what can go wrong, a writer cannot offer solutions to typical problems of the end-user.
*** Enter USE CASE
That’s why USE CASE was invented I suppose. It is the kind of scenario that starts with describing a “typical” situation in which the user (called an ACTOR) interacts with the system smoothly, without any hiccups. We first understand what the “healthy” condition is. In a Use Case that “main story” is referred to as the “Main Flow.”
Then comes all those situations in which things don’t go that well. That scenario(s) is(are) called “Alternative Flow(s).”  That describes the “pathology” of the system, so to speak.
As a SIDEBAR I can’t help but thinking that this is the reverse of the method applied in psychiatry where an understanding of the pathology leads the analyst to understand the “healthy” workings of the human mind.  In the software-hardware universe, we first understand the “healthy” in order to understand how to cope with the “pathology.”
Here is a very brief example of a Use Case:
——————————————-
ACTOR: Homeowner.
DESCRIPTION: This use case describes how a homeowner gets rid of the dandelions in her front yard.
——————————————-
BASIC FLOW Scenario:
1)      The Homeowner applies KillWeed brand pesticide, 20 oz. per 10 square yd of lawn.
2)      The Homeowner waters the lawn twice a day, before and after sunset.
3)      In three weeks, all dandelion disappear and the lawn looks much healthier than before.
——————————————-
ALTERNATIVE FLOW Scenario 1:
1)      The Homeowner applies too much KillWeed brand pesticide.
2)      The Homeowner waters the lawn twice a day, before and after sunset.
3)      In three weeks, all dandelion disappear together with the lawn, leaving behind a barren patch of earth.
——————————————-
ALTERNATIVE FLOW Scenario 2:
1)      The Homeowner applies not enough KillWeed brand pesticide.
2)      The Homeowner waters the lawn twice a day, before and after sunset.
3)      In three weeks, there are more dandelions than before and the lawn is browning out fast.
——————————————-

Resources:

http://www.developer.com/design/article.php/10925_2109801_2/Creating-Use-Case-Diagrams.htm
http://www.gatherspace.com/static/use_case_example.html
http://www.cs.colorado.edu/~kena/classes/6448/s05/reference/usecases/examples.html
http://www.andrew.cmu.edu/course/90-754/umlucdfaq.html
http://www.wilsonmar.com/1usecase.htm