Documentation/NewtonDocTesting

2016-09-26T06:50:38Z

Bmoss: Delorean repo link update

2015-11-19T04:51:42Z

Bmoss: /* 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.
; Orientation
: 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.
; Layout
: 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.
; Operators
: 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.

{| class="wikitable" style="text-align: center;"
|+ '''Audience environments'''
| align="center" style="background:#f0f0f0;"|'''Role'''
| align="center" style="background:#f0f0f0;"|'''Office'''
| align="center" style="background:#f0f0f0;"|'''Lab'''
| align="center" style="background:#f0f0f0;"|'''Data Center'''
|-
| style="text-align: left;" |Software Developer ||x || ||
|-
| style="text-align: left;" |Operator ||x ||x ||x
|-
| style="text-align: left;" |System Administrator ||x ||x ||
|-
| style="text-align: left;" |End User ||x || ||
|-
| style="text-align: left;" |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).

{| {{table}}
| align="center" style="background:#f0f0f0;"|'''Task'''
| align="center" style="background:#f0f0f0;"|'''Software developer'''
| align="center" style="background:#f0f0f0;"|'''Operator'''
| align="center" style="background:#f0f0f0;"|'''System administrator'''
| align="center" style="background:#f0f0f0;"|'''End user'''
| align="center" style="background:#f0f0f0;"|'''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
|}

Documentation/UserAnalysis

2015-11-19T04:41:38Z

Bmoss: /* User/task matrix */ add table

= 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.
; Orientation
: 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.
; Layout
: 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.
; Operators
: 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.

{| {{table}}
| align="center" style="background:#f0f0f0;"|'''Role'''
| align="center" style="background:#f0f0f0;"|'''Office'''
| align="center" style="background:#f0f0f0;"|'''Lab'''
| align="center" style="background:#f0f0f0;"|'''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).

{| {{table}}
| align="center" style="background:#f0f0f0;"|'''Task'''
| align="center" style="background:#f0f0f0;"|'''Software developer'''
| align="center" style="background:#f0f0f0;"|'''Operator'''
| align="center" style="background:#f0f0f0;"|'''System administrator'''
| align="center" style="background:#f0f0f0;"|'''End user'''
| align="center" style="background:#f0f0f0;"|'''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
|}