Documenting use cases

[freeman3101]

Use cases can be a very powerful mechanism to document specifications
that may be used for as a basis for internal software development, or
to form the basis of a RFP (Request for Proposal) document to be sent
to vendors in the search for that perfect solution.

To properly document such a specification a lot more information is
needed than the diagram itself. Detail documentation about the
elements and even the relationships may be needed.
What follows is a simple set of information we have found to be useful
in documenting use case diagrams and the elements on those diagrams.

We use the following approach:

Step one: Create the use case model

A starting point for the use case model would be the initial macro
analysis of the entire scope of the system. This typically involves
creating high level package diagrams to properly identify and segment
the different parts of the system required.

Once the packages are properly defined the use case diagrams are
modelled in which the actors (roles) and use cases (interactions/
functions) are modelled together with the relationships between them.
To understand the diagram often a textual description would be added
to ensure understanding of what the diagram represents. This may be
done in a brief summary of the scope of the diagrams, or a more
detailed description if the possibility of misinterpretation exists.

Step two: Document elements

The next step would be to document the individual elements.

An actor is normally named for the named for the role that is
represented. Additional information documented about the actor may
include the following and more:

* Brief description of the actor and the responsibilities
* Typical skills
* Description of interface (if the actor is an external system or
device)
* Nature of interface
* Complexity of interaction
* Other roles that the actor may play

The use case will be named with a verb and a noun. The verb indicates
the action is taken by the actor and the noun indicates the entity to
which this action is applied. Additional information to document may
include:

* The use case scope - A brief description describing what is done
when the use case is executed. It is normally written in terms of the
goal of the use case.
* Notes on whether the use case is targeted for automation (if
appropriate)
* Business rules that apply to the execution of the use case - these
may be preconditions which is everything that needs to be true before
the function can be performed, post conditions which is everything
that must be true after the function has been executed and invariants
which define rules that must be adhered to at all times.
* Scenarios - scenarios describe the detail steps behind the use case
that is executed in order for the use case to achieve its purpose.
This typically is defined in terms of a basic path and several
alternate paths. A basic path typically describes the normal execution
path whereas every alternate path will describe the sequence of
actions taken should and error, interruption, decision or business
rule failure occur that causes a deviation from the basic path.

Other options that may be described in the use case context might be
non-functional requirements and reference materials related to the use
case.

Non functional requirements often allow the audience to define other
requirements like performance requirements, display requirements, and
others that may not be functional in their nature.

Adequately describing use cases diagrams and their elements may
provide in itself a comprehensive mechanism from which an
understanding of requirements or vendor selection may take place. To
effectively design and implement systems more information is needed,
but we will discuss it in upcoming topics.

Happy Modelling!