Jump to: navigation, search

Difference between revisions of "Blueprint-restructure-documentation"

(→‎Goals)
Line 8: Line 8:
  
 
This blueprint describes a plan to restructure the OpenStack documentation to reduce redundancy and increase usability, clarity, and consistency.
 
This blueprint describes a plan to restructure the OpenStack documentation to reduce redundancy and increase usability, clarity, and consistency.
 +
 +
== Goals ==
 +
 +
The restructure aims to create the following main documents with the following goals:
 +
 +
{| class="wikitable"
 +
|-
 +
! Title !! Audience !! Description
 +
|-
 +
| ''OpenStack Installation Guide'' || Deployers
 +
||
 +
Step-by-step instructions for how to install and deploy OpenStack clusters.
 +
<br/>
 +
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.
 +
* An introduction to the OpenStack community, including how to get help.
 +
<br/>
 +
Exclude:
 +
* Unusual deployment scenarios
 +
|-
 +
| ''OpenStack Operations Guide'' || Deployers
 +
||
 +
Opinionated direction for how to design and operate OpenStack clusters.
 +
<br/>
 +
Exclude: 
 +
* Installation instructions
 +
* Configuration reference information
 +
|-
 +
| ''OpenStack Configuration Reference'' || Deployers
 +
||
 +
Lists configuration options available with OpenStack.
 +
<br/>
 +
Include:
 +
* Configuration files
 +
* Configuration options in each file
 +
* Configuration extensions
 +
* Use cases for each configuration feature
 +
<br/>
 +
Exclude:
 +
* API parameters
 +
|-
 +
| ''OpenStack User Guide'' || Users and developers
 +
||
 +
OpenStack cloud concepts and instructions for how to use an OpenStack cloud.
 +
<p/>
 +
Include:
 +
* Command-line tools and credentials
 +
* How to use Horizon dashboard
 +
* How to create images
 +
<br/>
 +
Exclude:
 +
* Cloud Application Architecture
 +
|-
 +
| ''OpenStack Command Reference'' || Users and developers
 +
||
 +
Command-line clients, with subcommands and required and optional parameters.
 +
<br/>
 +
Include:
 +
* Each command-line client
 +
* For each client, lists and describes subcommands and required and optional parameters
 +
<br/>
 +
Exclude:
 +
* Concepts (these go in the ''OpenStack User Guide'')
 +
* Installation instructions (these go in the ''OpenStack Installation Guide'')
 +
|-
 +
| ''OpenStack Developer Guide'' || Developers
 +
||
 +
Guidance for developing code for OpenStack. 
 +
|-
 +
| ''OpenStack <project> API Specification'' || Developers
 +
||
 +
API concepts followed by descriptions of API methods and parameters, with examples for each.
 +
<br/>
 +
Include:
 +
* Advanced guidance information
 +
|-
 +
| ''OpenStack API Reference'' || Developers
 +
||
 +
Searchable and comprehensive Web page that lists API methods and parameters, with examples for each.
 +
<br/>
 +
Exclude:
 +
* Advanced guidance information (this goes in the ''OpenStack <project> API Specification/s'')
 +
* Installation instructions
 +
* Descriptions of features longer than one sentence
 +
|}
  
 
== Design ==
 
== Design ==
Line 17: Line 103:
 
{| class="wikitable"
 
{| class="wikitable"
 
|-
 
|-
−
! Planned document !! Description !! Take material from || Include glossary?
+
! Planned document !! Description !! Take material from !! Include glossary?
 
|-
 
|-
−
| OpenStack Installation Guide || Step-by-step instructions for how to install and deploy an OpenStack cluster.  
+
| OpenStack Installation Guide || Install and deploy an OpenStack cluster.  
 
||  
 
||  
 
* OpenStack Basic Install Guide - Ubuntu 12.04
 
* OpenStack Basic Install Guide - Ubuntu 12.04
Line 30: Line 116:
 
Yes
 
Yes
 
|-
 
|-
−
| OpenStack Operations Guide || Opinionated direction on the design and operations of OpenStack clusters.  
+
| OpenStack Operations Guide || Design and operate OpenStack clusters.  
 
||  
 
||  
 
* OpenStack Operations Guide
 
* OpenStack Operations Guide
Line 38: Line 124:
 
Yes
 
Yes
 
|-
 
|-
−
| OpenStack Configuration Reference || Configuration options available with OpenStack.  
+
| OpenStack Configuration Reference || Configure OpenStack.  
 
||  
 
||  
 
* OpenStack <project> Administration Guide/s
 
* OpenStack <project> Administration Guide/s
Line 54: Line 140:
 
! Planned document !! Description !! Take material from !! Include glossary?
 
! Planned document !! Description !! Take material from !! Include glossary?
 
|-
 
|-
−
| OpenStack User Guide || OpenStack concepts and instructions for how to use an OpenStack cloud.   
+
| OpenStack User Guide || Complete user tasks on an OpenStack cloud.   
 
||  
 
||  
 
* OpenStack API Quick Start
 
* OpenStack API Quick Start
Line 64: Line 150:
 
Yes
 
Yes
 
|-
 
|-
−
| OpenStack Command Reference || OpenStack client commands.  
+
| OpenStack Command Reference || Run OpenStack client commands.  
 
||  
 
||  
 
* OpenStack Clients Guide
 
* OpenStack Clients Guide
Line 80: Line 166:
 
! Planned document !! Description !! Take material from !! Include glossary?
 
! Planned document !! Description !! Take material from !! Include glossary?
 
|-
 
|-
−
| OpenStack <project> API Specification || OpenStack API concepts, followed by descriptions of all API methods and parameters, with examples for each.  
+
| OpenStack <project> API Specification || Write applications by using, review, or extend OpenStack APIs.  
 
||  
 
||  
 
* OpenStack <project> API Dev Guides
 
* OpenStack <project> API Dev Guides
Line 86: Line 172:
 
Yes
 
Yes
 
|-
 
|-
−
| OpenStack API Reference || Web page that lists all API methods and parameters, with examples for each.  
+
| OpenStack API Reference || Write applications by using or extend OpenStack APIs.
 
||  
 
||  
 
* API Complete Reference  
 
* API Complete Reference  
Line 92: Line 178:
 
No
 
No
 
|-
 
|-
−
| OpenStack Compute API Developer Guide for Shell and Python || Guidance for developing OpenStack applications by using specific language bindings.  
+
| OpenStack Compute API Developer Guide for Shell and Python || Write Python applications by using the OpenStack APIs.
 
||  
 
||  
 
* Programming OpenStack Compute API with Shell and Python  
 
* Programming OpenStack Compute API with Shell and Python  
Line 98: Line 184:
 
Yes
 
Yes
 
|-
 
|-
−
| OpenStack Developer Guide || Guidance for developing code for OpenStack.   
+
| OpenStack Developer Guide || Develop code for OpenStack.   
 
||  
 
||  
 
* Continuous Integration (CI) Developer Documentation
 
* Continuous Integration (CI) Developer Documentation
Line 107: Line 193:
 
|}
 
|}
  
−
== Goals ==
 
−
 
−
The restructure aims to create the following main documents with the following goals:
 
  
−
{| class="wikitable"
 
−
|-
 
−
! Title !! Audience !! Description !! Notes
 
−
|-
 
−
| ''OpenStack Installation Guide'' || Deployers || Step-by-step instructions for how to install and deploy 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.
 
−
* An introduction to the OpenStack community, including how to get help.
 
−
<br/>
 
−
Exclude:
 
−
* Unusual deployment scenarios
 
−
|-
 
−
| ''OpenStack Operations Guide'' || Deployers || Opinionated direction for how to design and operate OpenStack clusters.
 
−
||
 
−
Exclude: 
 
−
* Installation instructions
 
−
* Configuration reference information
 
−
|-
 
−
| ''OpenStack Configuration Reference'' || Deployers || Lists configuration options available with OpenStack.
 
−
||
 
−
Include:
 
−
* Configuration files
 
−
* Configuration options in each file
 
−
* Configuration extensions
 
−
* Use cases for each configuration feature
 
−
<br/>
 
−
Exclude:
 
−
* API parameters
 
−
|-
 
−
| ''OpenStack User Guide'' || Users and developers || OpenStack cloud concepts and instructions for how to use an OpenStack cloud.
 
−
||
 
−
Include:
 
−
* Command-line tools and credentials
 
−
* How to use Horizon dashboard
 
−
* How to create images
 
−
<br/>
 
−
Exclude:
 
−
* Cloud Application Architecture
 
−
|-
 
−
| ''OpenStack Command Reference'' || Users and developers || For each command-line client,
 
−
||
 
−
Include:
 
−
* Each command-line client
 
−
* For each client, lists and describes subcommands and required and optional parameters
 
−
<br/>
 
−
Exclude:
 
−
* Concepts (these go in the ''OpenStack User Guide'')
 
−
* Installation instructions (these go in the ''OpenStack Installation Guide'')
 
−
|-
 
−
| ''OpenStack Developer Guide'' || Developers || Guidance for developing code for OpenStack. 
 
−
||
 
−
|-
 
−
| ''OpenStack <project> API Specification'' || Developers || API concepts followed by descriptions of API methods and parameters, with examples for each.
 
−
||
 
−
Include:
 
−
* Advanced guidance information
 
−
|-
 
−
| ''OpenStack API Reference'' || Developers || 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
 
−
* Descriptions of features longer than one sentence
 
−
|}
 
  
 
== Issues ==
 
== Issues ==

Revision as of 17:18, 14 May 2013

Summary

The OpenStack library was designed a few years ago. Since then, the library has grown without a specific organization. Also, we have learned how users interact with it.

This blueprint describes a plan to restructure the OpenStack documentation to reduce redundancy and increase usability, clarity, and consistency.

Goals

The restructure aims to create the following main documents with the following goals:

Title Audience Description
OpenStack Installation Guide Deployers

Step-by-step instructions for how to install and deploy 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.
  • An introduction to the OpenStack community, including how to get help.


Exclude:

  • Unusual deployment scenarios
OpenStack Operations Guide Deployers

Opinionated direction for how to design and operate OpenStack clusters.
Exclude:

  • Installation instructions
  • Configuration reference information
OpenStack Configuration Reference Deployers

Lists configuration options available with OpenStack.
Include:

  • Configuration files
  • Configuration options in each file
  • Configuration extensions
  • Use cases for each configuration feature


Exclude:

  • API parameters
OpenStack User Guide Users and developers

OpenStack cloud concepts and instructions for how to use an OpenStack cloud. <p/> Include:

  • Command-line tools and credentials
  • How to use Horizon dashboard
  • How to create images


Exclude:

  • Cloud Application Architecture
OpenStack Command Reference Users and developers

Command-line clients, with subcommands and required and optional parameters.
Include:

  • Each command-line client
  • For each client, lists and describes subcommands and required and optional parameters


Exclude:

  • Concepts (these go in the OpenStack User Guide)
  • Installation instructions (these go in the OpenStack Installation Guide)
OpenStack Developer Guide Developers

Guidance for developing code for OpenStack.

OpenStack <project> API Specification Developers

API concepts followed by descriptions of API methods and parameters, with examples for each.
Include:

  • Advanced guidance information
OpenStack API Reference Developers

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
  • Descriptions of features longer than one sentence

Design

Install and deploy a OpenStack cloud

Audience: Deployers of OpenStack clusters

Planned document Description Take material from 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

Yes

OpenStack Operations Guide Design and operate OpenStack clusters.
  • OpenStack Operations Guide
  • OpenStack <project> Administration Guide/s
  • <project> devref/s

Yes

OpenStack Configuration Reference Configure OpenStack.
  • OpenStack <project> Administration Guide/s
  • <project> devref/s

Yes

Use an OpenStack cloud

Audience: OpenStack cloud users and developers.

Planned document Description 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.
  • OpenStack Clients Guide

Yes

Develop applications with or extend OpenStack APIs

Audience: Developers

Planned document Description Take material from Include glossary?
OpenStack <project> API Specification 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 Compute API Developer Guide for Shell and Python Write Python applications by using the OpenStack APIs.
  • Programming OpenStack Compute API with Shell and Python

Yes

OpenStack Developer Guide Develop code for OpenStack.
  • Continuous Integration (CI) Developer Documentation
  • <project> devref/s

Yes


Issues

  • Lack of people to implement.
Retrieved from "https://wiki.openstack.org/w/index.php?title=Blueprint-restructure-documentation&oldid=22529"