Re: Summary of modular user-story-based docs terminology
by Pete Travis
On Jan 20, 2017 10:38, "Petr Bokoc" <pbokoc(a)redhat.com> wrote:
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.
*snip*
I really like this model, especially the module classes. Server side
includes came up at some point in an assembly-related discussion I had with
Bex at some point; that's always seemed like a crafty way to catch a
security lecture from a sysadmin :P
That said, server side includes could allow us to more easily assemble
articles using components from multiple source repositories, afaik
something that no publishing tool can do easily. Kevin, would you please
weigh in on the idea?
-- Pete
6 years, 8 months
Summary of modular user-story-based docs terminology
by Petr Bokoc
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 topicon 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-basedcan 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.
6 years, 8 months
