Jump to: navigation, search

Difference between revisions of "Blueprint-restructure-documentation"

(→‎Install, Configure, and Run)
 
(152 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 5: Line 5:
  
 
== Summary ==
 
== 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.
+
The OpenStack documentation library was designed a few years ago.  
  
−
This blueprint describes a plan to restructure the OpenStack documentation to reduce redundancy and increase usability, clarity, and consistency.
+
Since then, the library has grown without a specific organization. Also, doc contributors have learned how users interact with it.
  
−
== Goals ==
+
This blueprint describes a plan to restructure the OpenStack documentation to:<br />
  
−
The restructure aims to create the following main documents with the following goals:
+
* 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:
 
{| class="wikitable"
 
{| class="wikitable"
 
|-
 
|-
−
! Title !! Goals
+
! Audience !! Tasks !! Docs
−
|-
 
−
| ''OpenStack Installation Guide''
 
−
||
 
−
* 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; basic explanatory text for command steps, enabling first time users to understand why they are performing them, and; an introduction to the OpenStack community, including how to get help.
 
−
* Exclude unusual deployment scenarios.
 
−
|-
 
−
| ''OpenStack Operations Guide''
 
−
||
 
−
* Provide opinionated direction for ''deployers'' about how to design, set up, and run OpenStack clusters.
 
−
* Exclude installation instructions and configuration reference information.
 
−
|-
 
−
| ''OpenStack Configuration Reference''
 
−
||
 
−
* List configuration options available with OpenStack.
 
−
* Include configuration files, configuration options in each file, configuration extensions, and use cases for each configuration feature.
 
−
* Exclude API parameters.
 
−
|-
 
−
| ''OpenStack User Guide''
 
−
||
 
−
* Explain OpenStack cloud concepts and describe how to use an OpenStack cloud.
 
−
* Include command-line tools and credentials, how to use Horizon dashboard, and how to create images.
 
−
* Exclude Cloud application architecture.
 
−
|-
 
−
| ''OpenStack Command Reference''
 
−
||
 
−
* Describe command-line clients and their subcommands and required and optional parameters.
 
−
* Exclude concepts (these go in the ''OpenStack User Guide'') or installation instructions (these go in the ''OpenStack Installation Guide'').
 
 
|-
 
|-
−
| ''OpenStack Developer Guide''
+
| OpenStack deployers || Install, configure, and run OpenStack clusters.
 
||  
 
||  
−
* Describe how to develop code for OpenStack. 
+
* ''OpenStack Installation Guide''
 +
* ''OpenStack Operations Guide''
 +
* ''OpenStack Configuration Reference''
 +
* ''OpenStack Cloud Administrator Guide''
 
|-
 
|-
−
| ''OpenStack <project> API Specification''
+
| 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"
 
||  
 
||  
−
* Explain API concepts and describe API methods and parameters, with examples for each.
+
* ''OpenStack End User Guide''
−
* Include advanced guidance information.
+
* ''OpenStack Admin User Guide''
 
|-
 
|-
−
| ''OpenStack API Reference''
+
| OpenStack contributors and application developers || Extend the OpenStack APIs.<br />
−
||  
+
Write applications that run on top of an OpenStack cloud.
−
* Provide ''developers'' with a searchable and comprehensive Web page that lists API methods and parameters, with examples for each.
+
||
−
* 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 API Guide''
 +
* ''OpenStack API Complete Reference'' web pages - one page for each OpenStack project
 
|}
 
|}
  
−
== Design ==
+
== Deliverables - Deployers ==
−
=== Install, Configure, and Run ===
+
 
−
'''Audience:''' Deployers who want to install, configure, and run OpenStack clusters.
+
'''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 ===
 +
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.<br /><br />
 +
 
 +
'''Source  material'''
  
−
{| class="wikitable"
 
−
|-
 
−
! Planned document !! Describes how to !! Take material from !! Product info / release info !! Include glossary?
 
−
|-
 
−
| ''OpenStack Installation Guide'' || Install and deploy an OpenStack cluster.
 
−
||
 
 
* OpenStack Basic Install Guide - Ubuntu 12.04
 
* OpenStack Basic Install Guide - Ubuntu 12.04
 
* OpenStack Basic Install Guide - Fedora 18
 
* OpenStack Basic Install Guide - Fedora 18
Line 75: Line 67:
 
* OpenStack Install and Deploy Manual - Red Hat
 
* OpenStack Install and Deploy Manual - Red Hat
 
* OpenStack <project> Administration Guide/s
 
* OpenStack <project> Administration Guide/s
−
* <project> devref/s
+
* ''project'' devref/s
−
||
+
 
−
Grizzly, 2013.1
+
=== OpenStack Operations Guide ===
−
||
+
 
−
Yes
+
'''Purpose'''
−
|-
+
 
−
| ''OpenStack Operations Guide'' || Design and operate 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''.
 +
* Exclude installation instructions and configuration reference information.<br /><br />
 +
 
 +
'''Source  material'''
 +
 
 
* OpenStack Operations Guide
 
* OpenStack Operations Guide
−
* OpenStack <project> Administration Guide/s
+
* OpenStack High Availability Guide?? Or does this stay in its own book?
−
* <project> devref/s
+
* OpenStack ''project'' Administration Guide/s
−
||
+
* ''project'' devref/s
−
Grizzly, 2013.1
+
 
−
||
+
=== OpenStack Configuration Reference ===
−
Yes
+
 
−
|-
+
'''Purpose'''
−
| ''OpenStack Configuration Reference'' || Configure OpenStack.  
+
 
−
||
+
* List configuration options available with OpenStack. Use auto-generation to generate options from the code.
−
* OpenStack <project> Administration Guide/s
+
* Include configuration files, configuration options in each file, configuration extensions, and use cases for each configuration feature.
−
* <project> devref/s
+
* Exclude API parameters.<br /><br />
−
||
+
 
−
Grizzly, 2013.1
+
'''Source  material'''
−
||
+
 
−
Yes
+
* 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.<br /><br />
 +
 
 +
'''Source  material'''
 +
 
 +
* OpenStack ''project'' Administration Guide/s
 +
* ''project'' devref/s
 +
 
 +
 
 +
'''Blueprints:''' [[Blueprint-os-admin-docs|Blueprint - OpenStack Administration Guide]], [[Blueprint-os-modularize-admin-docs|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.
 +
<br />
 +
'''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.
 +
<br />
 +
'''Product info:''' Havana, 2013.1<br />
 +
 
 +
'''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 />
 +
 
 +
 
 +
'''Blueprint:''' [[Blueprint-os-api-docs|Blueprint - OpenStack API Documentation]]
 +
 
 +
=== OpenStack API Guide (new) ===
 +
 
 +
See [[Blueprint-os-api-docs|blueprint]] for details.
 +
 
 +
=== OpenStack ''project'' API Reference/s (delete) ===
  
−
=== Use ===
+
See [[Blueprint-os-api-docs|blueprint]] for details.
−
'''Audience''': Users of OpenStack clouds.
 
  
−
{| class="wikitable"
+
=== OpenStack API Complete Reference (multiple web pages) ===
−
|-
 
−
! Planned document !! Describes how to !! Take material from !! Include glossary?
 
−
|-
 
−
| ''OpenStack User Guide'' || Complete user tasks on an OpenStack cloud. 
 
−
||
 
−
* OpenStack API Quick Start
 
−
* Python Developer Documentation
 
−
* Language Bindings Documentation
 
−
* OpenStack Clients Guide
 
−
* <project> devref/s
 
−
||
 
−
Yes
 
−
|-
 
−
| ''OpenStack Command Reference'' || Run OpenStack client commands on an OpenStack cloud.
 
−
||
 
−
* OpenStack Clients Guide
 
−
||
 
−
Yes
 
−
|-
 
−
|}
 
  
−
=== Develop ===
+
See [[Blueprint-os-api-docs|blueprint]] for details.
−
'''Audience''': Developers who want to develop applications with or extend OpenStack APIs.
 
  
−
{| class="wikitable"
 
−
|-
 
−
! Planned document !! Describes how to !! Take material from !! Include glossary?
 
−
|-
 
−
| ''OpenStack <project> API Specification/s'' || Write applications by using, review, or extend OpenStack APIs.
 
−
||
 
−
* OpenStack <project> API Dev Guides
 
−
||
 
−
Yes
 
−
|-
 
−
| ''OpenStack API Reference'' || Write applications by using or extend OpenStack APIs.
 
−
||
 
−
* API Complete Reference
 
−
||
 
−
No
 
−
|-
 
−
| ''OpenStack Developer Guide'' || Develop code for OpenStack. 
 
−
||
 
−
* Continuous Integration (CI) Developer Documentation
 
−
* OpenStack Compute API Developer Guide for Shell and Python
 
−
* <project> devref/s
 
−
||
 
−
Yes
 
−
|-
 
−
|}
 
  
−
== 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.

Retrieved from "https://wiki.openstack.org/w/index.php?title=Blueprint-restructure-documentation&oldid=52405"