Sabine Ocker, Comtech Services
June 15, 2019
The topic of last month’s CIDM Round Table was User Stories and Technical Publications. Although user stories are traditionally a software development tool in the Agile methodology, we discussed how they can also assist the technical documentation process.
The purpose of a user story is to generate understanding of a software feature from the end user’s perspective. In one sentence, a user story will describe user type, what that user wants, and why.
User stories usually have the following structure:
The “As a…” part of a user story represents the person using the software or hardware, so knowing not only who your user is, but what tasks they need to focus on is essential to creating successful and effective user stories or Technical Product Documentation. User personas help to provide the granular details of the user role and goals.
“I want…” represents the requirement expressed from the user’s point of view. In terms of documentation, this also represents the task to be documented. These requirement statements focus on one specific user goal or capability rather than a systems-oriented technical specification. Goal statements don’t include user interface particulars.
“So that…” describes the benefit or value proposition from the end user perspective and explains why the goal makes sense. Benefit statements can also provide a means for prioritizing user stories.
Other components of a user story include details on the acceptance criteria—a value for the priority or importance of the requirement, as well as an estimate from the developer on the level of effort required to complete the user story.
User stories are an important aspect of minimalist writing and user-centered design, which is the centerpiece of the modern technical writing process. Because user stories are written from the user perspective, they aid in keeping the user as the main focus for any design, development, or documentation efforts. From the documentation perspective, since a user story can only focus on a single user, it is easy to group content geared towards a specific user role together.
But resources are limited. Focusing on a specific user type is a reminder to include only the most important information a user needs to execute the task. This will help them complete their immediate goal, not necessarily to use every feature or part of the product. If content cannot align well to a user story, then eliminate it if it already exists, or simply do not create if it doesn’t.
The “I want…” component of a user story aligns very well to another principle of minimalism, which is to choose an action-oriented approach. Each user story represents a task or a part of a task in the corresponding product documentation.
User stories are also useful to chatbots. Chatbots need virtually the same information as is contained in the “As a…” and “I want…” components in order to determine the role and intent of the user to give them the correct information, which corresponds with the task associated with the “I want…” component.
Assuming your organization has the proper metadata available and the content is tagged appropriately and at the correct level, user stories can be valuable input to enable your Support chatbot to give your users exactly the right micro-content they are looking for.
In almost the same way as a chatbot might deliver the right task to a specific end user trying to complete a specific goal, taxonomies also help to guide users to the right content more quickly and effectively. A user story aligns well to several important enterprise taxonomy branches, including user and product. Providing that the metadata is associated with the content and your delivery platform can expose it, each one of the pieces of the user story could be used as pre-search facets or post-search filters.
Although the “With product…” component is not a core part of the user story today, we advocate Technical Product documentation add this for taxonomy development. User stories do not explicitly state how, but they are all tied to a product or product feature development.
Another way in which user stories help Technical Product documentation is by facilitating better cross-departmental communications. Writers, developers, and product managers all need to have a shared understanding of the requirements expressed in each user story. User stories start a conversation, which becomes a negotiation between the groups and results in focused, actionable steps for each team to execute against.
If you want to learn more about the power of user stories and their role in each one of the benefits described in this brief article, Comtech Services offers two Workshops designed to help you:
- Minimalism: Creating Content People Really Need: Practical application of the four principles of minimalism to select appropriate content for your users, structure it consistently, author it for each understanding, and make it readily accessible.
- Developing a User-Centric Content Strategy: Techniques for learning about your users, their goals, and their work, creating personas that will serve as a decision-making tool throughout the life-cycle of your project or product, and making user-centered design decisions in all aspects of documentation development.