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:
- How to drill a hole in a flat surface (wood or plastic, metal, masonry).
- How to select the right screw for fastening items.
- How to drive screws (phillips, flat-head) with your drill.
- How to stir paint with your drill.
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:
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.
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.
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.