Difference between revisions of "Blueprint-restructure-documentation"
(→Use) |
(→Goals) |
||
Line 15: | Line 15: | ||
{| class="wikitable" | {| class="wikitable" | ||
|- | |- | ||
− | ! Title | + | ! Title !! Goals |
|- | |- | ||
− | | ''OpenStack Installation Guide'' | + | | ''OpenStack Installation Guide'' |
|| | || | ||
− | Step-by-step instructions for how to install and | + | Step-by-step instructions for ''deployers'' for how to install, configure, and run OpenStack clusters. |
<br/> | <br/> | ||
Include: | Include: | ||
Line 29: | Line 29: | ||
* Unusual deployment scenarios | * Unusual deployment scenarios | ||
|- | |- | ||
− | | ''OpenStack Operations Guide'' | + | | ''OpenStack Operations Guide'' |
|| | || | ||
− | Opinionated direction for how to design and operate OpenStack clusters. | + | Opinionated direction for ''deployers'' for how to design, set up, and operate OpenStack clusters. |
<br/> | <br/> | ||
Exclude: | Exclude: | ||
Line 37: | Line 37: | ||
* Configuration reference information | * Configuration reference information | ||
|- | |- | ||
− | | ''OpenStack Configuration Reference'' | + | | ''OpenStack Configuration Reference'' |
|| | || | ||
Lists configuration options available with OpenStack. | Lists configuration options available with OpenStack. | ||
Line 50: | Line 50: | ||
* API parameters | * API parameters | ||
|- | |- | ||
− | | ''OpenStack User Guide'' | + | | ''OpenStack User Guide'' |
|| | || | ||
− | OpenStack cloud concepts and | + | Explains OpenStack cloud concepts and describes how to use an OpenStack cloud. |
<p/> | <p/> | ||
Include: | Include: | ||
Line 62: | Line 62: | ||
* Cloud Application Architecture | * Cloud Application Architecture | ||
|- | |- | ||
− | | ''OpenStack Command Reference'' | + | | ''OpenStack Command Reference'' |
|| | || | ||
− | + | Describes command-line clients and their subcommands and required and optional parameters. | |
<br/> | <br/> | ||
Include: | Include: | ||
Line 74: | Line 74: | ||
* Installation instructions (these go in the ''OpenStack Installation Guide'') | * Installation instructions (these go in the ''OpenStack Installation Guide'') | ||
|- | |- | ||
− | | ''OpenStack Developer Guide'' | + | | ''OpenStack Developer Guide'' |
|| | || | ||
− | + | Provides guidance for developing code for OpenStack. | |
|- | |- | ||
− | | ''OpenStack <project> API Specification'' | + | | ''OpenStack <project> API Specification'' |
|| | || | ||
− | API concepts | + | Explains API concepts and describes API methods and parameters, with examples for each. |
<br/> | <br/> | ||
Include: | Include: | ||
Line 87: | Line 87: | ||
| ''OpenStack API Reference'' || Developers | | ''OpenStack API Reference'' || Developers | ||
|| | || | ||
− | + | Provides a searchable and comprehensive Web page that lists API methods and parameters, with examples for each. | |
<br/> | <br/> | ||
Exclude: | Exclude: |
Revision as of 17:35, 14 May 2013
- Launchpad Entry: restructure-documentation
- Created: Tom Fifield
- Contributors: Diane Fleming
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 reduce redundancy and increase usability, clarity, and consistency.
Goals
The restructure aims to create the following main documents with the following goals:
Title | Goals | |
---|---|---|
OpenStack Installation Guide |
Step-by-step instructions for deployers for how to install, configure, and run OpenStack clusters.
| |
OpenStack Operations Guide |
Opinionated direction for deployers for how to design, set up, and operate OpenStack clusters.
| |
OpenStack Configuration Reference |
Lists configuration options available with OpenStack.
| |
OpenStack User Guide |
Explains OpenStack cloud concepts and describes how to use an OpenStack cloud. <p/> Include:
| |
OpenStack Command Reference |
Describes command-line clients and their subcommands and required and optional parameters.
| |
OpenStack Developer Guide |
Provides guidance for developing code for OpenStack. | |
OpenStack <project> API Specification |
Explains API concepts and describes API methods and parameters, with examples for each.
| |
OpenStack API Reference | Developers |
Provides a searchable and comprehensive Web page that lists API methods and parameters, with examples for each.
|
Design
Install, Configure, and Run
Audience: Deployers who want to install, configure, and run OpenStack clusters.
Planned document | Describes how to | Take material from | Include glossary? |
---|---|---|---|
OpenStack Installation Guide | Install and deploy an OpenStack cluster. |
|
Yes |
OpenStack Operations Guide | Design and operate OpenStack clusters. |
|
Yes |
OpenStack Configuration Reference | Configure OpenStack. |
|
Yes |
Use
Audience: Users of OpenStack clouds.
Planned document | Describes how to | Take material from | Include glossary? |
---|---|---|---|
OpenStack User Guide | Complete user tasks on an OpenStack cloud. |
|
Yes |
OpenStack Command Reference | Run OpenStack client commands on an OpenStack cloud. |
|
Yes |
Develop
Audience: Developers who want to develop applications with or extend OpenStack APIs.
Planned document | Describes how to | Take material from | Include glossary? |
---|---|---|---|
OpenStack <project> API Specification/s | Write applications by using, review, or extend OpenStack APIs. |
|
Yes |
OpenStack API Reference | Write applications by using or extend OpenStack APIs. |
|
No |
OpenStack Compute API Developer Guide for Shell and Python | Write Python applications by using the OpenStack APIs. |
|
Yes |
OpenStack Developer Guide | Develop code for OpenStack. |
|
Yes |
Issues
- Lack of people to implement.