Re: Plain English explanation of use cases??

[Thom Randolph <thom -at- halcyon -dot- com>]

Jean:

This isn't so much a synopsis of others' writings,
as it is my first-hand experiences with usage scenarios.
We've found user-based scenarios quite helpful in
our documentation. We don't often include them inside the
documentation, but we use them in the document specifications
and for deciding the content. In our case, we are somewhat
lucky, because the software release is based on them, which
makes it much easier to choose which scenarios are
appropriate.

In the normal development process, the product team does
a lot of brainstorming, which yields incredibly long
lists of small and large features. The Product Managers
take those features and envision how the customer would
use the product. These are very high level things the
user would do. For example, "Send and Receive email".
There should be a usage scenario that covers every major
aspect of the product feature-set.

As the estimates of development and test time are made,
it becomes clear what parts of the product are going to
be more difficult or time consuming. In interviews with
potential customers the PMs further learn which features
are most important to customers. In a magical moment
of inspiration, the Product Manager declares the priorities
of the usage scenarios. From those scenarios, the priority
is then applied to the features. If features are a low
priority based on their expected usage, they are dropped
or delayed from the next release. Same goes for features
that are not needed by any of the usage scenarios.

If we're lucky, the documentation group is alerted to,
and allowed to participate in the customer meetings. In
them, we stay focused on what skills they are brining to
the table; what things they already know. We use that to
create a "customer profile", and we extend that profile
to include special-case users. If the Marketing plan
indicates that our customer profile doesn't completely
cover the target market, we can see where we need more
customer interviews. Or, if the extrapolation isn't too
far-fetched, we can extend the customer profile to cover
those people as well.

This is where the documentation scenarios begin. Using
the high-level usage scenarios, we develop our own, much
more detailed scenarios. These include specific steps the
user must perform to accomplish the tasks in the high-level
scenarios. Now that we know what the customer will be
doing, we can extrapolate what information they will
require to perform that. This isn't limited to what we
think they will or won't know when they sit down to use
the product; it's an inventory of knowledge they will
require. Whether they already have it, or gain it from
our documentation isn't really important in the scenario.

Okay. So now we've got a good idea of how the user will
use the product; what specific things they'll be doing
based on the high-level usage scenarios. And by extension,
we have a long list of the information they will need to
do those things. We also have a very detailed understanding
of what things the customers will already know. The things
we expect them to know become our assumptions; the difference
between what's needed to perform the tasks and what they
already know is the information we need to cover in the
documentation.

Some of our products rely, contain, or are integrated with
other large products that we sell. Because of this, we can
look at the component documentation and see if some of the
must-document information is already captured there. If so,
that becomes material that we reference in our documentation.

The things left are those that the customer doesn't already
know, and those that are not documented elsewhere. So, we
now have a list of 80-90% of the topics our documentation
will need to cover. The other 10-20% will come in things
we need to describe to them anyway, like product architecture,
introductory material, and so on.

As the product changes, as features are added or removed,
we can easily adjust the usage scenarios to cover them,
and that leads directly to the documentation item lists,
and then to the documentation itself. It also helps the
entire product team see why particular features are so
important. If feature A is cut, no one on the development
or test teams might care, but the users will care because
four out of ten usage scenarios are no longer possible
without that feature. This also directly impacts the
Marketing predictions for sales and market acceptance.

One place where usage scenarios can be directly applied
to the documentation is in tutorials. Depending on the
complexity of the product, we can construct core-subject,
or theme-based tutorials, based on the scenarios. This
can provide the reader with exposure to many of the
product capabilities, since the users drive the scenarios,
which drive the features, and which drive the documentation.
Also, it means the tutorials will be much less contrived,
and the user will be much more able to envision themselves
being productive with the product. After all, the scenarios
are based on what they want to do with the product.

That is how we apply "usage scenarios" to our documentation
work. It has very much taken the guess-work out of deciding
what's important and what's not. While it's not nearly as
rigorous as data-flow diagrams, I'm not convinced that it's
possible or wise to create a data-flow diagram that includes
ALL the interactions of a user with a system. Data-flow
diagrams are best (in my opinion) in defining how components
interact, not how users accomplish tasks. It's difficult to
see the user experience from a data-flow diagram, but it's
easy to empathize with the story of a user trying to get
their work done.

I hope the above helps you,

Thom Randolph
thom -at- halcyon -dot- com



At 09:10 PM 1/21/00 +1000, you wrote: