Jump to: navigation, search

Difference between revisions of "Blueprint-restructure-documentation"

(Audiences)
 
(111 intermediate revisions by 4 users not shown)
Line 1: Line 1:
 
+
{{ImplementedFeature}}
 
* '''Launchpad Entry''':  [https://blueprints.launchpad.net/openstack-manuals/+spec/restructure-documentation restructure-documentation]
 
* '''Launchpad Entry''':  [https://blueprints.launchpad.net/openstack-manuals/+spec/restructure-documentation restructure-documentation]
 
* '''Created''': Tom Fifield
 
* '''Created''': Tom Fifield
Line 11: Line 11:
 
This blueprint describes a plan to restructure the OpenStack documentation to:<br />
 
This blueprint describes a plan to restructure the OpenStack documentation to:<br />
  
* Provide a clear roadmap through the documentation library for different audiences.
+
* Provide a clear roadmap through the documentation library for different audiences: Deployers, users, and developers.
 
* Reduce redundancy.
 
* Reduce redundancy.
 
* Increase usability, clarity, and consistency.
 
* Increase usability, clarity, and consistency.
  
 
== Audiences ==
 
== Audiences ==
The restructure provides the following deliverables for the following audiences:  
+
The restructure enables these audiences to complete tasks by using the following docs:
 
{| class="wikitable"
 
{| class="wikitable"
 
|-
 
|-
 
! Audience !! Tasks !! Docs
 
! Audience !! Tasks !! Docs
 
|-
 
|-
| OpenStack cloud deployers || Install, configure, and run OpenStack clusters.  
+
| OpenStack deployers || Install, configure, and run OpenStack clusters.  
 
||  
 
||  
 
* ''OpenStack Installation Guide''
 
* ''OpenStack Installation Guide''
 
* ''OpenStack Operations Guide''  
 
* ''OpenStack Operations Guide''  
 
* ''OpenStack Configuration Reference''
 
* ''OpenStack Configuration Reference''
 +
* ''OpenStack Cloud Administrator Guide''
 
|-
 
|-
|  OpenStack cloud users || Perform tasks in an OpenStack cloud through the Horizon dashboard, the OpenStack command-line clients, or directly through the OpenStack APIs.
+
|  OpenStack end and admin users || Perform tasks in an OpenStack cloud through:
 +
* The Horizon dashboard
 +
* The OpenStack command-line clients
 +
* Directly through the OpenStack APIs - see the "OpenStack API Guide"
 
||  
 
||  
* ''OpenStack User Guide''
+
* ''OpenStack End User Guide''
* ''OpenStack Command Reference''
+
* ''OpenStack Admin User Guide''
 
|-
 
|-
| OpenStack developers || Extend the OpenStack APIs or write applications that run on top of an OpenStack cloud.
+
| OpenStack contributors and application developers || Extend the OpenStack APIs.<br />
 +
Write applications that run on top of an OpenStack cloud.
 
||   
 
||   
* ''OpenStack Developer Guide''
+
* ''OpenStack API Guide''
* ''OpenStack <project> API Specification/s''
+
* ''OpenStack API Complete Reference'' web pages - one page for each OpenStack project
* ''OpenStack API Reference'' web page
 
 
|}
 
|}
  
== Deliverables ==
+
== Deliverables - Deployers ==
 +
 
 +
'''Audience''': Deployers who want to install, configure, and run OpenStack clusters. <br />
 +
'''Product info:''' Havana, 2013.1<br />
 +
'''Include common glossary?''' Yes
  
 
=== OpenStack Installation Guide ===
 
=== OpenStack Installation Guide ===
 +
Blueprint:[[Install-with-multiple-architectures]]
 +
 +
'''Purpose'''
  
 
* Provide step-by-step instructions for ''deployers'' about how to install, configure, and run OpenStack clusters.  
 
* Provide step-by-step instructions for ''deployers'' about how to install, configure, and run OpenStack clusters.  
Line 47: Line 58:
 
* Include basic explanatory text for command steps, enabling first time users to understand why they are performing them.
 
* Include basic explanatory text for command steps, enabling first time users to understand why they are performing them.
 
* Introduce the OpenStack community, including how to get help.  
 
* Introduce the OpenStack community, including how to get help.  
* Exclude unusual deployment scenarios.
+
* Exclude unusual deployment scenarios.<br /><br />
 +
 
 +
'''Source  material'''
 +
 
 +
* OpenStack Basic Install Guide - Ubuntu 12.04
 +
* OpenStack Basic Install Guide - Fedora 18
 +
* OpenStack Install and Deploy Manual - Ubuntu
 +
* OpenStack Install and Deploy Manual - Red Hat
 +
* OpenStack <project> Administration Guide/s
 +
* ''project'' devref/s
  
 
=== OpenStack Operations Guide ===
 
=== OpenStack Operations Guide ===
 +
 +
'''Purpose'''
  
 
* Provide opinionated direction for ''deployers'' about how to design, set up, and run OpenStack clusters.  
 
* Provide opinionated direction for ''deployers'' about how to design, set up, and run OpenStack clusters.  
 
* Include information currently in the ''OpenStack High Availability Guide''.
 
* Include information currently in the ''OpenStack High Availability Guide''.
* Exclude installation instructions and configuration reference information.
+
* Exclude installation instructions and configuration reference information.<br /><br />
  
=== OpenStack Configuration Reference ===
+
'''Source  material'''
  
* List configuration options available with OpenStack.
+
* OpenStack Operations Guide
* Include configuration files, configuration options in each file, configuration extensions, and use cases for each configuration feature.
+
* OpenStack High Availability Guide?? Or does this stay in its own book?
* Exclude API parameters.
+
* OpenStack ''project'' Administration Guide/s
 +
* ''project'' devref/s
  
=== OpenStack User Guide ===
+
=== OpenStack Configuration Reference ===
  
* Explain OpenStack cloud concepts and describe how to use an OpenStack cloud.
+
'''Purpose'''
* Include command-line tools and credentials, how to use Horizon dashboard, and how to create images.
 
* Exclude Cloud application architecture.
 
  
=== OpenStack Command Reference ===
+
* List configuration options available with OpenStack. Use auto-generation to generate options from the code.
 
+
* Include configuration files, configuration options in each file, configuration extensions, and use cases for each configuration feature.
* Describe command-line clients and their subcommands and required and optional parameters.  
+
* Exclude API parameters.<br /><br />
* Exclude concepts (these go in the ''OpenStack User Guide'') or installation instructions (these go in the ''OpenStack Installation Guide'').
 
  
=== OpenStack Developer Guide ===
+
'''Source  material'''
  
* Describe how to develop code for OpenStack.
+
* OpenStack ''project'' Administration Guide/s
 +
* ''project'' devref/s
  
=== OpenStack <''project''> API Specification ===
+
=== OpenStack Cloud Administrator Guide ===
  
* Explain API concepts and describe API methods and parameters, with examples for each.
+
'''Purpose'''
* Include advanced guidance information.
 
  
=== OpenStack API Reference (web page) ===
+
* Provide guidance to day-to-day cloud administrators about how to perform administrative tasks.<br /><br />
  
* Provide ''developers'' with a searchable and comprehensive Web page that lists API methods and parameters, with examples for each.
+
'''Source  material'''
* Exclude advanced guidance information (this goes in the ''OpenStack <project> API Specification/s''), installation instructions, or feature descriptions that are longer than one sentence.
 
  
 +
* OpenStack ''project'' Administration Guide/s
 +
* ''project'' devref/s
  
The following section details the restructure plan.
 
  
== Design ==
+
'''Blueprints:''' [[Blueprint-os-admin-docs|Blueprint - OpenStack Administration Guide]], [[Blueprint-os-modularize-admin-docs|Blueprint - Modularize OpenStack Administration Guide]],
=== Install, Configure, and Run ===
 
'''Audience:''' Deployers who want to install, configure, and run OpenStack clusters.
 
  
{| class="wikitable"
+
== Deliverables - Admin and End Users  ==
|-
 
! New title !! Describes how to !! Take material from !! Release info !! Include glossary?
 
|-
 
| ''OpenStack Installation Guide'' || Install and deploy an OpenStack cluster.
 
||
 
* OpenStack Basic Install Guide - Ubuntu 12.04
 
* OpenStack Basic Install Guide - Fedora 18
 
* OpenStack Install and Deploy Manual - Ubuntu
 
* OpenStack Install and Deploy Manual - Red Hat
 
* OpenStack <project> Administration Guide/s
 
* <project> devref/s
 
||
 
Havana, 2013.1
 
||
 
Yes
 
|-
 
| ''OpenStack Operations Guide'' || Design and operate OpenStack clusters.
 
||
 
* OpenStack Operations Guide
 
* OpenStack High Availability Guide
 
* OpenStack <project> Administration Guide/s
 
* <project> devref/s
 
||
 
Havana, 2013.1
 
||
 
Yes
 
|-
 
| ''OpenStack Configuration Reference'' || Configure OpenStack.
 
||
 
* OpenStack <project> Administration Guide/s
 
* <project> devref/s
 
||
 
Havana, 2013.1
 
||
 
Yes
 
|}
 
 
 
=== Use ===
 
 
'''Audience''':  
 
'''Audience''':  
 
* Users of OpenStack clouds who perform tasks through the Horizon dashboard or the OpenStack command-line clients.  
 
* Users of OpenStack clouds who perform tasks through the Horizon dashboard or the OpenStack command-line clients.  
* Developers who develop applications on top of OpenStack by using the OpenStack APIs.
+
* Beginning application developers who want to develop applications on top of OpenStack by using the OpenStack APIs.
 
<br />
 
<br />
 
'''Roadmap''':  
 
'''Roadmap''':  
Line 140: Line 120:
 
* Then, they use the OpenStack APIs to create scalable applications.
 
* Then, they use the OpenStack APIs to create scalable applications.
 
<br />
 
<br />
'''Strategy''':
+
'''Product info:''' Havana, 2013.1<br />
* For the API Reference and the API Specifications, the plan is to use a common set of WADL files to generate the docs. Currently, the API reference page is generated from WADL files, but the API Specifications are not. This strategy will ensure that contributors must update one set of files: Both sets of docs will be generated from this single set of WADLs.
+
 
 +
'''Include common glossary?''' Yes <br />
 +
 
 +
'''Blueprint:''' [[Blueprint-os-user-docs|Blueprint - OpenStack User Documentation]]
 +
 
 +
=== OpenStack End User Guide (new) ===
 +
 
 +
See [[Blueprint-os-user-docs|blueprint]] for details.
 +
 
 +
=== OpenStack Admin User Guide (new) ===
 +
 
 +
See [[Blueprint-os-user-docs|blueprint]] for details.
 +
 
 +
== Deliverables - Application Developers and OpenStack Contributors ==
 +
 
 +
'''Audience:''' Developers who want to extend the OpenStack APIs or write applications by using the OpenStack APIs.<br />
 +
 
 +
'''Release info:''' API v''n''<br />
 +
 
 +
'''Include common glossary?''' Yes<br />
 +
 
 +
'''Strategy:'''
 +
# Eliminate the existing API References.
 +
# Add an API Guide that describes API concepts, general information, and ways to access the APIs.
 +
# Move material currently in the API Reference/s into the WADL files to source the API Complete Reference pages. One web page for each OpenStack project. Source code samples from nova code base where possible. <br />
 +
 
 +
 
 +
End result: One API Reference page for each project and one API Guide.  
 
<br />
 
<br />
{| class="wikitable"
 
|-
 
! New title !! Describes how to !! Take material from !! Release info !! Include glossary?
 
|-
 
| ''OpenStack User Guide'' || Use an OpenStack cloud. 
 
||
 
* OpenStack API Quick Start
 
* Python Developer Documentation
 
* Language Bindings Documentation
 
* OpenStack Clients Guide
 
* <''project''> devref/s
 
||
 
Havana, 2013.1
 
||
 
Yes
 
|-
 
| ''OpenStack Command Reference'' || Run OpenStack client commands on an OpenStack cloud.
 
||
 
* OpenStack Clients Guide
 
||
 
Havana, 2013.1
 
||
 
Yes
 
|-
 
| ''OpenStack <project> API Specification/s'' || Write applications by using, review, or extend the OpenStack APIs.
 
||
 
* OpenStack <''project''> API Specification/s
 
||
 
API v''n''
 
||
 
Yes
 
|-
 
| ''OpenStack API Reference'' || Write applications by using or extend OpenStack APIs.
 
||
 
* API Complete Reference
 
||
 
API v''n''
 
||
 
No
 
|-
 
|}
 
  
=== Develop ===
 
'''Audience''': Developers who want to extend the OpenStack APIs or write applications by using the OpenStack APIs.
 
  
{| class="wikitable"
+
'''Blueprint:''' [[Blueprint-os-api-docs|Blueprint - OpenStack API Documentation]]
|-
+
 
! New title !! Describes how to !! Take material from !! Release info !! Include glossary?
+
=== OpenStack API Guide (new) ===
|-
+
 
| ''OpenStack Developer Guide'' || Extend the OpenStack APIs or write applications by using the OpenStack APIs.
+
See [[Blueprint-os-api-docs|blueprint]] for details.
||
+
 
* Continuous Integration (CI) Developer Documentation
+
=== OpenStack ''project'' API Reference/s (delete) ===
* OpenStack Compute API Developer Guide for Shell and Python
+
 
* <''project''> devref/s
+
See [[Blueprint-os-api-docs|blueprint]] for details.
||
+
 
API v''n''
+
=== OpenStack API Complete Reference (multiple web pages) ===
||
+
 
Yes
+
See [[Blueprint-os-api-docs|blueprint]] for details.
|-
+
 
|}
 
  
== Issues ==
 
* Lack of people to implement.
 
----
 
 
[[Category:Spec]]
 
[[Category:Spec]]

Latest revision as of 18:13, 15 May 2014

Warning.svg Old Design Page

This page was used to help design a feature that has been implemented. As a result, this page is unlikely to be updated and could contain outdated information. It was last updated on 2014-05-15

Summary

The OpenStack documentation library was designed a few years ago.

Since then, the library has grown without a specific organization. Also, doc contributors have learned how users interact with it.

This blueprint describes a plan to restructure the OpenStack documentation to:

  • Provide a clear roadmap through the documentation library for different audiences: Deployers, users, and developers.
  • Reduce redundancy.
  • Increase usability, clarity, and consistency.

Audiences

The restructure enables these audiences to complete tasks by using the following docs:

Audience Tasks Docs
OpenStack deployers Install, configure, and run OpenStack clusters.
  • OpenStack Installation Guide
  • OpenStack Operations Guide
  • OpenStack Configuration Reference
  • OpenStack Cloud Administrator Guide
OpenStack end and admin users Perform tasks in an OpenStack cloud through:
  • The Horizon dashboard
  • The OpenStack command-line clients
  • Directly through the OpenStack APIs - see the "OpenStack API Guide"
  • OpenStack End User Guide
  • OpenStack Admin User Guide
OpenStack contributors and application developers Extend the OpenStack APIs.

Write applications that run on top of an OpenStack cloud.

  • OpenStack API Guide
  • OpenStack API Complete Reference web pages - one page for each OpenStack project

Deliverables - Deployers

Audience: Deployers who want to install, configure, and run OpenStack clusters.
Product info: Havana, 2013.1
Include common glossary? Yes

OpenStack Installation Guide

Blueprint:Install-with-multiple-architectures

Purpose

  • Provide step-by-step instructions for deployers about how to install, configure, and run OpenStack clusters.
  • Include easy-to-follow, lightweight, command-by-command steps for installing an OpenStack cluster of defined architecture.
  • Include basic explanatory text for command steps, enabling first time users to understand why they are performing them.
  • Introduce the OpenStack community, including how to get help.
  • Exclude unusual deployment scenarios.

Source material

  • OpenStack Basic Install Guide - Ubuntu 12.04
  • OpenStack Basic Install Guide - Fedora 18
  • OpenStack Install and Deploy Manual - Ubuntu
  • OpenStack Install and Deploy Manual - Red Hat
  • OpenStack <project> Administration Guide/s
  • project devref/s

OpenStack Operations Guide

Purpose

  • Provide opinionated direction for deployers about how to design, set up, and run OpenStack clusters.
  • Include information currently in the OpenStack High Availability Guide.
  • Exclude installation instructions and configuration reference information.

Source material

  • OpenStack Operations Guide
  • OpenStack High Availability Guide?? Or does this stay in its own book?
  • OpenStack project Administration Guide/s
  • project devref/s

OpenStack Configuration Reference

Purpose

  • List configuration options available with OpenStack. Use auto-generation to generate options from the code.
  • Include configuration files, configuration options in each file, configuration extensions, and use cases for each configuration feature.
  • Exclude API parameters.

Source material

  • OpenStack project Administration Guide/s
  • project devref/s

OpenStack Cloud Administrator Guide

Purpose

  • Provide guidance to day-to-day cloud administrators about how to perform administrative tasks.

Source material

  • OpenStack project Administration Guide/s
  • project devref/s


Blueprints: Blueprint - OpenStack Administration Guide, Blueprint - Modularize OpenStack Administration Guide,

Deliverables - Admin and End Users

Audience:

  • Users of OpenStack clouds who perform tasks through the Horizon dashboard or the OpenStack command-line clients.
  • Beginning application developers who want to develop applications on top of OpenStack by using the OpenStack APIs.


Roadmap:

  • Users ramp up on cloud computing by using the Horizon dashboard and the OpenStack command-line clients.
  • Then, they use the OpenStack APIs to create scalable applications.


Product info: Havana, 2013.1

Include common glossary? Yes

Blueprint: Blueprint - OpenStack User Documentation

OpenStack End User Guide (new)

See blueprint for details.

OpenStack Admin User Guide (new)

See blueprint for details.

Deliverables - Application Developers and OpenStack Contributors

Audience: Developers who want to extend the OpenStack APIs or write applications by using the OpenStack APIs.

Release info: API vn

Include common glossary? Yes

Strategy:

  1. Eliminate the existing API References.
  2. Add an API Guide that describes API concepts, general information, and ways to access the APIs.
  3. Move material currently in the API Reference/s into the WADL files to source the API Complete Reference pages. One web page for each OpenStack project. Source code samples from nova code base where possible.


End result: One API Reference page for each project and one API Guide.


Blueprint: Blueprint - OpenStack API Documentation

OpenStack API Guide (new)

See blueprint for details.

OpenStack project API Reference/s (delete)

See blueprint for details.

OpenStack API Complete Reference (multiple web pages)

See blueprint for details.