Use Case Driven Documentation

drilling

Yesterday we wrote about focusing our documentation on what our users are trying to accomplish. With a structured requirements approach, or with an interaction-design driven approach, we’ve already solved half the problem – determining what to document.

Our proposed documentation approach is to write about what users are doing with the software, not what the software can do for the users. Using a power drill as an example, we proposed the following representative approach:

  1. How to drill a hole in a flat surface (wood or plastic, metal, masonry).
  2. How to select the right screw for fastening items.
  3. How to drive screws (phillips, flat-head) with your drill.
  4. How to stir paint with your drill.
  5. etc…

Suddenly, the documentation is helping us to achieve our goals.

Extending Structured Requirements

When we use a structured requirements approach, we have established a framework for defining the problems that our software will solve. We articulate how people solve those problems with use cases. These use cases define exactly what we need to document.

When we view structured requirements, they look like the following diagram:

structured requirements

From Non-Functional Requirements Equal Rights Amendment

We extend this structure by leveraging the fact that the use cases identify the highest priority tasks that users will perform to achieve goals. These are therefore the highest priority tasks to document. The documentation represents how a user would achieve a use case, with the implementation that we’ve created.

structured documentation

We can even trace each portion of our documentation work to the use case that it supports.

Extending Interaction Design

With interaction design, we are again focusing on what people intend to achieve while using our software. Even if we are writing game software (which is designed to be played without a “goal” in the traditional sense), the user still has a goal of “being entertained.”

With interaction design, we would write documentation that demonstrates the way that scenarios play out with the given implementation that we created.

Even when combining interaction design and structured requirements into a hybrid approach, we still have a source from which to define our documentation needs – the scenario.

Summary

We’ve previously defined the benefits of documenting what users do with our software instead of documenting what our software can do for users. In this article we present a framework for defining and tracing that documentation – building upon use cases or scenarios. This documentation approach makes for software that is easier to use, and therefore better.

  • Scott Sehlhorst

    Scott Sehlhorst is a product management and strategy consultant with over 30 years of experience in engineering, software development, and business. Scott founded Tyner Blain in 2005 to focus on helping companies, teams, and product managers build better products. Follow him on LinkedIn, and connect to see how Scott can help your organization.