Summary of modular user-story-based docs terminology

[Petr Bokoc <pbokoc@xxxxxxxxxx>]

Hello everyone,

We've been working on modular documentation internally (in Red Hat) for a while, and since our efforts and the modularization/modernization initiative Fedora Docs align to a large degree, we want to share with you what we have so far.

The following is a short digest of our progress so far. We still need to decide how to put everything together and how to keep track of various articles, this is mostly thoughts on various types of content. Hopefully you'll find this useful; I'll follow this up later with some additional ideas.

Modular Documentation - Definitions used for RHEL docs

NOTE: This document is not intended as a complete reference guide for documentation-related terminology.

Module = a building block of information with a well-organized structure that can be combined with other modules into a larger assembly; reused piece of content

• Procedural module = describes steps to accomplish a task

• Conceptual module = explains a concept; i.e. not based on task

• Reference module = lists links to related reference information, such as man pages or other documentation, including other modules or assemblies

Assembly = A collection of modules -- a docs realization of a user story

User story = a short description of something the user wants or needs to do to achieve a goal.

• Example: As an administrator, I want to set up authentication to a critical system in my infrastructure (gateway VPN, accounting system) to only allow users authenticated via strong authentication methods (two-factor authentication).

• As opposed to a use case = a description of interactions between the system and the user or other systems.

We don’t use the term topic on purpose:

• It’s ambiguous - people use topic for a piece of documentation, a user story, a short chunk of content, etc. -> better to avoid to prevent misunderstanding

• Therefore, topic-based can mean a number of things -> better to avoid.

User-story-based docs = docs developed to support a user story; for our purposes, the same as use case-based docs.

Modular docs = docs structured into modules and assemblies

What are user stories?

With the shift from feature-based to user story-based docs, one particular question comes up a lot: What the heck are user stories and how are they different from use cases? Because our documentation should focus on what users do, user stories tell us exactly what we need to know to understand the users' situation. We can always extract that information from a use case as well, but the advantage of user stories is that they are clear, concise, and without fluff that we as writers don't need in order to understand the users' goal.

Contrasting User Stories and Use Cases

Definition:	A short description of something the user does to achieve a goal.	A description of interactions between the system and the user, components of the system, or the system and other systems.
Views the situation from:	The perspective of a user.	The perspective of a product and its features.
Focuses on:	The outcome as perceived by the user.	What the product does and how it does it (includes product requirements, specification, scope).
Example:	As an office worker, I want to be able to easily switch between standing and sitting, so that I prevent back pain and other health issues associated with prolonged periods of sitting at a computer.   Note: This user story follows a common template for user stories in the form of "As a <type of user>, I want <some goal> so that <some reason>."	Ergonomic work space solution - a standing desk that allows switching between standing and sitting. The standing desk: Is motorized, with a button a person can press to adjust the height; the height must span up to 150 cm to be usable also by people 200 cm tall Is made from easy-to-clean and durable material to withstand standard office conditions (spilled tea, scratches): table top - polyester, legs - steel Has large enough work surface to comfortably fit 2 monitors, one laptop docking station, small personal items. Can hold the weight of 100 kg (standard office equipment and a person sitting on the desk) Meets safety requirements per EU standards for office equipment Has attractive design to fit in modern office spaces ...   Note: A use case like this can also include other ergonomic solutions (such as an adjustable sit-stand wall mount for monitors) and compare their parameters (such as ease of installation, price, ease of use, etc.).

 

What's the Difference between Feature-based Docs and User-story-based Docs?

Feature-based docs:

• explain how to perform isolated actions
• it's up to the user to put the piece together and accomplish their goal

User story-based docs (we also call them assemblies because our plan is to assemble them from reusable modules):

• document actions and commands in a broader context of the user story
• provide complete scenarios with a defined goal

Neither of these approaches is necessarily right or wrong. They just have different purposes:

• Feature-based docs work just fine for users who want to learn how a feature works.
• User story-based docs are focused on users who want to immediately start doing things. (The user story-based approach doesn't contradict learning, though. One of the best ways to learn somethings is to just start doing it.)

Helping people get things done is at the heart of this initiative. If done right, user story-based docs will save users time they would otherwise need to spend on learning how features work and then figuring out how to actually use them. 

_______________________________________________
docs mailing list -- docs@xxxxxxxxxxxxxxxxxxxxxxx
To unsubscribe send an email to docs-leave@xxxxxxxxxxxxxxxxxxxxxxx