Difference between revisions of "Blueprint-restructure-documentation"
(→Use an OpenStack cloud) |
(→Develop applications with or extend OpenStack APIs) |
||
Line 78: | Line 78: | ||
{| class="wikitable" | {| class="wikitable" | ||
|- | |- | ||
− | ! Planned document !! Description | + | ! 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 | + | | 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 | + | | 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 | + | | 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 | + | | OpenStack Developer Guide || Guidance for developing code for OpenStack. |
− | <project> devref/s | + | || |
− | + | * Continuous Integration (CI) Developer Documentation | |
− | + | * <project> devref/s | |
+ | || | ||
+ | Yes | ||
|- | |- | ||
|} | |} |
Revision as of 16:58, 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 | Include | Exclude |
---|---|---|---|---|
OpenStack Installation Guide | Deployers | Step-by-step instructions for how to install and deploy OpenStack clusters. |
|
|
OpenStack Operations Guide | Deployers | Opinionated direction for how to design and operate OpenStack clusters. | - |
|
OpenStack Configuration Reference | Deployers | Lists configuration options available with OpenStack. |
|
|
OpenStack User Guide | Users and developers | OpenStack cloud concepts and instructions for how to use an OpenStack cloud. |
|
|
OpenStack Command Reference | Users and developers | For each command-line client, |
|
|
OpenStack Developer Guide | Developers | Example | Example | |
OpenStack <project> API Specification | Developers | API concepts followed by descriptions of API methods and parameters, with examples for each. | Example | |
OpenStack API Reference | Developers | Searchable and comprehensive Web page that lists API methods and parameters, with examples for each. |
- |
|
Issues
- Lack of people to implement.