Jump to: navigation, search


< Documentation
Revision as of 04:51, 19 November 2015 by Bmoss (talk | contribs) (Audience environments)

OpenStack documentation user analysis

To date, OpenStack documentation has grown organically in response to rapidly changing project priorities. As a documentation group, we want to refocus the existing documentation so that it grows in a considered and scalable way. In order to do so, we need to understand first of all who our users are, and what results they hope to achieve from reading the documentation.

Purpose of documentation

Support users in deploying, maintaining, and using OpenStack.

Usability goals

Best effort should be made for OpenStack documentation to adhere to the following guidelines:

Search and navigation
Users should be able to find the topic using search, or by browsing to the topic. If more than one topic is required, users should be able to navigate to the next topic with ease. Each guide should have an abstract that states the purpose of the guide and the intended audience.
Users should know at all times where they are in the documentation relative to the whole, and relative to where they were previously. Provide topics to help users orient to thought processes and complex tasks.
Decision making
Users should be able to choose the appropriate topics, decide what inputs to provide the software, and interpret their results.
Task completion
Users should follow an efficient path through the topics in the documentation to accomplish their goals.
Task generalization
Users should be able to extrapolate the information in the documentation to situations that are not explicitly documented. For example, they should be able to determine what inputs are appropriate for various applications.
Diagnosis and recovery from errors
Users should be able to learn how to diagnose a problem, correct it, and possibly prevent it in the future.
Highlight Hazards
Clearly highlight hazards the user may encounter and explain the consequences of potentially damaging actions.
Match between documentation and the real world terminology and concepts
The documentation should use language and concepts that are familiar to users, and may be dependent on their role (e.g. admin vs end user). Incorporate keywords that typical users would search on is critical and consider SEO metadata.
Minimalist writing
Topics should avoid information that is irrelevant. Every extra unit of information in a topic competes with the relevant information, which diminishes the findability of relevant information.
Careful consideration should be given to the presentation of content. Consider whether information is best conveyed as a paragraph, list, or graphic. Chunk content intelligently.
Consistency and standards
Users should not have to wonder whether different words, situations, or actions mean the same thing. It adds to cognitive load and detracts from their ability to quickly complete the task. Follow platform, software, and domain conventions. Adhere to the OpenStack docs conventions: http://docs.openstack.org/contributor-guide/index.html
Integration with software
Users should not have to exit their software workflow to access documentation. Provide search access to documentation from the product and context sensitive help, where possible.

User analysis

This audience analysis is an in-depth look at the users of the existing OpenStack documentation suite. As a result of this analysis, we will develop a set of personas that will guide future documentation development. This analysis will also inform the delivery mechanism and location of the guides, the format and design of the information itself, and the information pathways used by the readers to locate information and discover new topics.

Audience profile

Software Developers
assist with software design specifications, present ideas for improvements, write code and test the product before going live.
responsible for installing and configuring hardware, software and related infrastructure.
System administrators
deploy and manage tenants/projects in an installed OpenStack environment. Need to have a good understanding of the OpenStack architecture, software installation and configuration, and know how to do basic troubleshooting.
End users
create and manage VMs on deployed tenants/projects.
Management (CTO/CFO)
need to know what problem OpenStack solves. Need to understand the benefits of the current version of OpenStack compared to previous releases.

Audience environments

The table below shows the audiences and their physical and operational environment. The environments present no special requirements impacting document design.

Audience environments
Role Office Lab Data Center
Software Developer x
Operator x x x
System Administrator x x
End User x
Management (CTO/CFO) x

Needs analysis

  • Require step-by-step tutorials for getting started and more comprehensive information moving beyond simple proof of concepts
  • Require concepts, screenshots and diagrams to understand how it all fits together
  • Need to understand all the moving parts, in order to diagnose and resolve problems in each sphere of responsibility

High-Level task list

These tasks have been identified as critical decision points during OpenStack install and use. Each of these tasks encompass many smaller subtasks, and can be performed by one or more individual audiences:

  • Understanding the problems solved by OpenStack
  • Selecting services
  • Planning the installation
  • Performing the installation
  • Setting up networking
  • Creating projects
  • Creating instances
  • Maintaining projects
  • Maintaining instances
  • Troubleshooting problems
  • Ongoing maintenance tasks

User/task matrix

The user/task matrices below show the relationship between tasks and the user. The probability of a user performing the task is evaluated on a scale of 1 (low) to 10 (high).

Task Software developer Operator System administrator End user Management
Understanding the problems solved by OpenStack 10 8 8 8 8
Selecting services 10 10 1 1 1
Planning the installation 5 10 7 1 1
Performing the installation 5 10 7 1 1
Setting up networking 5 10 10 1 1
Creating projects 5 10 10 1 1
Creating instances 5 10 10 10 1
Maintaining projects 5 5 10 1 1
Maintaining instances 5 5 10 10 1
Troubleshooting problems 8 8 8 7 1
Ongoing maintenance tasks 1 10 10 1 1