Jump to: navigation, search

Difference between revisions of "Blueprint-restructure-documentation"

(Develop applications with or extend OpenStack APIs)
(Goals)
Line 113: Line 113:
 
{| class="wikitable"
 
{| class="wikitable"
 
|-
 
|-
! Title !! Audience !! Description !! Include !! Exclude
+
! Title !! Audience !! Description !! Notes
 
|-
 
|-
| ''OpenStack Installation Guide'' || Deployers || Step-by-step instructions for how to install and deploy OpenStack clusters. ||
+
| ''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
 
* 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.  
 
* 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.  
 
* An introduction to the OpenStack community, including how to get help.  
||
+
<br/>
 +
Exclude:
 
* Unusual deployment scenarios
 
* Unusual deployment scenarios
 
|-
 
|-
| ''OpenStack Operations Guide'' || Deployers || Opinionated direction for how to design and operate OpenStack clusters. || -
+
| ''OpenStack Operations Guide'' || Deployers || Opinionated direction for how to design and operate OpenStack clusters.  
||
+
||
 +
Exclude: 
 
* Installation instructions
 
* Installation instructions
 
* Configuration reference information
 
* Configuration reference information
Line 129: Line 132:
 
| ''OpenStack Configuration Reference'' || Deployers || Lists configuration options available with OpenStack.
 
| ''OpenStack Configuration Reference'' || Deployers || Lists configuration options available with OpenStack.
 
||
 
||
 +
Include:
 
* Configuration files  
 
* Configuration files  
 
* Configuration options in each file
 
* Configuration options in each file
 
* Configuration extensions
 
* Configuration extensions
 
* Use cases for each configuration feature  
 
* Use cases for each configuration feature  
||
+
<br/>
 +
Exclude:
 
* API parameters
 
* API parameters
 
|-
 
|-
 
| ''OpenStack User Guide'' || Users and developers || OpenStack cloud concepts and instructions for how to use an OpenStack cloud.  
 
| ''OpenStack User Guide'' || Users and developers || OpenStack cloud concepts and instructions for how to use an OpenStack cloud.  
 
||
 
||
 +
Include:
 
* Command-line tools and credentials
 
* Command-line tools and credentials
 
* How to use Horizon dashboard
 
* How to use Horizon dashboard
 
* How to create images
 
* How to create images
||
+
<br/>
 +
Exclude:
 
* Cloud Application Architecture  
 
* Cloud Application Architecture  
 
|-
 
|-
 
| ''OpenStack Command Reference'' || Users and developers || For each command-line client,  
 
| ''OpenStack Command Reference'' || Users and developers || For each command-line client,  
 
||  
 
||  
* Describes each command-line client  
+
Include:
 +
* Each command-line client  
 
* For each client, lists and describes subcommands and required and optional parameters
 
* For each client, lists and describes subcommands and required and optional parameters
||
+
<br/>
 +
Exclude:
 
* Concepts (these go in the ''OpenStack User Guide'')
 
* Concepts (these go in the ''OpenStack User Guide'')
 
* Installation instructions (these go in the ''OpenStack Installation Guide'')
 
* Installation instructions (these go in the ''OpenStack Installation Guide'')
 
|-
 
|-
| ''OpenStack Developer Guide'' || Developers || Example || Example
+
| ''OpenStack Developer Guide'' || Developers || Instructions for developing applications by using OpenStack APIs.
 +
||  
 
|-
 
|-
| ''OpenStack <project> API Specification'' || Developers || API concepts followed by descriptions of API methods and parameters, with examples for each. || Example
+
| ''OpenStack <project> API Specification'' || Developers || API concepts followed by descriptions of API methods and parameters, with examples for each.  
 +
||  
 
|-
 
|-
 
| ''OpenStack API Reference'' || Developers || Searchable and comprehensive Web page that lists API methods and parameters, with examples for each.  
 
| ''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'')  
 
* Advanced guidance information (this goes in the ''OpenStack <project> API Specification/s'')  
 
* Installation instructions
 
* Installation instructions

Revision as of 17:04, 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.

Design

Install and deploy a OpenStack cloud

Audience: Deployers of OpenStack clusters

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 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 Opinionated direction on the design and operations of OpenStack clusters.
  • OpenStack Operations Guide
  • OpenStack <project> Administration Guide/s
  • <project> devref/s

Yes

OpenStack Configuration Reference Configuration options available with 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 OpenStack concepts and instructions for how to use an OpenStack cloud.
  • OpenStack API Quick Start
  • Python Developer Documentation
  • Language Bindings Documentation
  • OpenStack Clients Guide
  • <project> devref/s

Yes

OpenStack Command Reference 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 OpenStack API concepts, followed by descriptions of all API methods and parameters, with examples for each.
  • OpenStack <project> API Dev Guides

Yes

OpenStack API Reference Web page that lists all API methods and parameters, with examples for each.
  • API Complete Reference

No

OpenStack Compute API Developer Guide for Shell and Python Guidance for developing OpenStack applications by using specific language bindings.
  • Programming OpenStack Compute API with Shell and Python

Yes

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

Yes

Goals

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

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.


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.

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 For each command-line client,

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 Instructions for developing applications by using OpenStack APIs.
OpenStack <project> API Specification Developers API concepts followed by descriptions of API methods and parameters, with examples for each.
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 that are longer than one sentence

Issues

  • Lack of people to implement.