Difference between revisions of "Blueprint-restructure-documentation"
(→Goals) |
(→Goals) |
||
| Line 21: | Line 21: | ||
Step-by-step instructions for ''deployers'' for how to install, configure, and run OpenStack clusters. | Step-by-step instructions for ''deployers'' for how to install, configure, and run OpenStack clusters. | ||
<br/> | <br/> | ||
| − | + | Includes: | |
* 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/> | <br/> | ||
| − | + | Excludes: | |
* Unusual deployment scenarios | * Unusual deployment scenarios | ||
|- | |- | ||
| Line 33: | Line 33: | ||
Opinionated direction for ''deployers'' for how to design, set up, and operate OpenStack clusters. | Opinionated direction for ''deployers'' for how to design, set up, and operate OpenStack clusters. | ||
<br/> | <br/> | ||
| − | + | Excludes: | |
* Installation instructions | * Installation instructions | ||
* Configuration reference information | * Configuration reference information | ||
| Line 41: | Line 41: | ||
Lists configuration options available with OpenStack. | Lists configuration options available with OpenStack. | ||
<br/> | <br/> | ||
| − | + | Includes: | |
* Configuration files | * Configuration files | ||
* Configuration options in each file | * Configuration options in each file | ||
| Line 47: | Line 47: | ||
* Use cases for each configuration feature | * Use cases for each configuration feature | ||
<br/> | <br/> | ||
| − | + | Excludes: | |
* API parameters | * API parameters | ||
|- | |- | ||
| Line 54: | Line 54: | ||
Explains OpenStack cloud concepts and describes how to use an OpenStack cloud. | Explains OpenStack cloud concepts and describes how to use an OpenStack cloud. | ||
<p/> | <p/> | ||
| − | + | Includes: | |
* 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/> | <br/> | ||
| − | + | Excludes: | |
* Cloud Application Architecture | * Cloud Application Architecture | ||
|- | |- | ||
| Line 66: | Line 66: | ||
Describes command-line clients and their subcommands and required and optional parameters. | Describes command-line clients and their subcommands and required and optional parameters. | ||
<br/> | <br/> | ||
| − | + | Includes: | |
* Each command-line client | * 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/> | <br/> | ||
| − | + | Excludes: | |
* 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'') | ||
| Line 82: | Line 82: | ||
Explains API concepts and describes API methods and parameters, with examples for each. | Explains API concepts and describes API methods and parameters, with examples for each. | ||
<br/> | <br/> | ||
| − | + | Includes: | |
* Advanced guidance information | * Advanced guidance information | ||
|- | |- | ||
| Line 89: | Line 89: | ||
Provides ''developers'' with a searchable and comprehensive Web page that lists API methods and parameters, with examples for each. | Provides ''developers'' with a searchable and comprehensive Web page that lists API methods and parameters, with examples for each. | ||
<br/> | <br/> | ||
| − | + | Excludes: | |
* 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:36, 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/> Includes:
|
| 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 |
Provides developers with 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.
