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 !! | + | ! 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, | ||
|| | || | ||
− | * | + | 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 || | + | | ''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 <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
- Launchpad Entry: restructure-documentation
- Created: Tom Fifield
- Contributors: Diane Fleming
Contents
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. |
|
Yes |
OpenStack Operations Guide | Opinionated direction on the design and operations of OpenStack clusters. |
|
Yes |
OpenStack Configuration Reference | Configuration options available with OpenStack. |
|
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. |
|
Yes |
OpenStack Command Reference | OpenStack client commands. |
|
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. |
|
Yes |
OpenStack API Reference | Web page that lists all API methods and parameters, with examples for each. |
|
No |
OpenStack Compute API Developer Guide for Shell and Python | Guidance for developing OpenStack applications by using specific language bindings. |
|
Yes |
OpenStack Developer Guide | Guidance for developing code for OpenStack. |
|
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:
|
OpenStack Operations Guide | Deployers | Opinionated direction for how to design and operate OpenStack clusters. |
Exclude:
|
OpenStack Configuration Reference | Deployers | Lists configuration options available with OpenStack. |
Include:
|
OpenStack User Guide | Users and developers | OpenStack cloud concepts and instructions for how to use an OpenStack cloud. |
Include:
|
OpenStack Command Reference | Users and developers | For each command-line client, |
Include:
|
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:
|
Issues
- Lack of people to implement.