Documentation Based on User Stories

Documentation can either focus on describing product features and the way they can be used, or it can start with identifying user needs and then explaining how to achieve specific goals.

Robert KratkyThere are numerous approaches to writing documentation, but one of the fundamental distinctions a doc writer must make is whether the resulting doc's goal is to:

• Describe "features" of a product, software, solution, etc., and how to use these features, or
• Explain what actions to take in order to perform a task to achieve a specific goal

Both approaches have valid uses, but there are areas or use cases where one is better than the other. It can also depend on who is writing the documentation and who is the intended audience.

Feature-based versus action-oriented docs

A typical manual page on a Unix-like system is a good example of feature-based documentation. Ideally, it contains an exhaustive list of all features (options, commands, parameters) of a program, it explains what the features are good for, and it provides examples of how to use them. The measure of quality in the case of this type of documentation is comprehensiveness and thoroughness.

On the other hand, a recipe in a cookbook is a classic example of action-oriented documentation that guides the user towards the completion of a specific goal by explaining clear-cut steps. A good recipe outlines the various prerequisites (ingredients, tools, equipment) and explains what to do with them and in what order to achieve a desired result. This type of documentation should strive to be concise and illustrative.

Consider these two examples:

There is a time and place for both types of documentation. The first column is reference-style content. It lists and describes the various attributes of a product and tells the user how to make use of them. It's most useful when the user wants to learn about all aspects of the product or for reference purposes, such as debugging. The second column is concerned with a specific goal, and it takes the user from point A to point B. To that end, it explains only the features or concepts of the product that need to be understood for achieving the defined result. It's most useful when the user has a task at hand that needs to be completed.

User stories

Borrowing from agile terminology, action-oriented documentation is often based on user stories. A user story is a definition of a process whereby a goal is accomplished. In agile development, user stories are employed to justify why any effort should be expended towards implementing new features or modifying existing ones and to describe the use of the feature from a user's point of view.

Most commonly, the following template is used for identifying user stories: As <type of user>, I want <what?>, so that <why?>.

For example, a user story can look like this:

As an administrator, I want to be able to connect to a server, so that I can manage user accounts.

The level of detail a user story describes can differ, which means that a high-level user story (often called an epic) can consist of a number of lower-level user stories.

Documentation based on user stories

Action-oriented docs can be based on user stories, which helps documentation writers make sure they write about things users actually need to know about. A user story is only valid if it is based on actual user needs. This is an important consideration that should not be overlooked because it can help reduce the amount of content that needs to be developed and maintained.

To arrive at a valid user story, input should be gathered from all involved parties. In an open source project, this can include developers, testers, users, and documentation writers. In an enterprise environment, feedback from customers is required, along with input from developers, support teams, product management, and content-strategy roles.

Which is better: feature-based or action-oriented docs?

Ideally, both types of documentation would be well represented, and users could choose the type that better fits their situation. A prospective contributor to a project would read the comprehensive reference-style doc to learn about all aspects of an application. A casual user or an admin would read the user story-based doc to find out how to perform a certain procedure to accomplish the immediate goal.

In reality, documentation writers need to consider the capacity of their team not only for authoring docs but also for maintenance. When resources are scarce, it is often better to start with documentation based on user stories because it can make useful information available relatively quickly, allowing users to start testing the product and providing feedback.

The user story-based approach is also a good choice when a documentation team is faced with the task of maintaining or modernizing an existing set of legacy, feature-based documentation. Instead of being stretched thin trying to maintain and improve large volumes of content that may not be needed or that are difficult for users to navigate, it makes sense to gradually convert the existing docs to user-story based pieces, leaving out the parts where valid user stories can't be established.

It's also easier to attract new contributors to user-story based documentation because the learning curve for starting to document a specific procedure is less steep than when a potential writer is expected to start documenting an application's entire feature set.

To sum up

Both feature-oriented documentation and action-oriented documentation, which can be based on user stories, are useful for different purposes, and writers should weigh the pros and cons of both approaches before committing to either one.

In an ideal world of no limits on time or other resources, complete versions of feature-based and action-oriented documentation would be written. In our real world, it may be best to focus on action-oriented documentation based on user stories to better target user needs and reduce the burden on the docs team.