Difference between revisions of "Blueprint-restructure-documentation"
(→Use) |
(→Use) |
||
Line 111: | Line 111: | ||
* Users of OpenStack clouds who perform tasks through the Horizon dashboard or the OpenStack command-line clients. | * Users of OpenStack clouds who perform tasks through the Horizon dashboard or the OpenStack command-line clients. | ||
* Developers who develop applications on top of OpenStack by using the OpenStack APIs. | * Developers who develop applications on top of OpenStack by using the OpenStack APIs. | ||
− | + | <br /> | |
'''Roadmap''': | '''Roadmap''': | ||
* Users ramp up on cloud computing by using the Horizon dashboard and the OpenStack command-line clients. | * Users ramp up on cloud computing by using the Horizon dashboard and the OpenStack command-line clients. | ||
* Then, they use the OpenStack APIs to create scalable applications. | * Then, they use the OpenStack APIs to create scalable applications. | ||
− | + | <br /> | |
− | Strategy: | + | '''Strategy''': |
* For the API Reference and the API Specifications, the plan is to use a common set of WADL files to generate the docs. Currently, the API reference page is generated from WADL files, but the API Specifications are not. This strategy will ensure that contributors must update one set of files: Both sets of docs will be generated from this single set of WADLs. | * For the API Reference and the API Specifications, the plan is to use a common set of WADL files to generate the docs. Currently, the API reference page is generated from WADL files, but the API Specifications are not. This strategy will ensure that contributors must update one set of files: Both sets of docs will be generated from this single set of WADLs. | ||
− | + | <br /> | |
{| class="wikitable" | {| class="wikitable" | ||
|- | |- |
Revision as of 15:06, 15 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 |
|
OpenStack Operations Guide |
|
OpenStack Configuration Reference |
|
OpenStack User Guide |
|
OpenStack Command Reference |
|
OpenStack Developer Guide |
|
OpenStack <project> API Specification |
|
OpenStack API Reference |
|
The following section details the restructure plan.
Design
Install, Configure, and Run
Audience: Deployers who want to install, configure, and run OpenStack clusters.
New title | Describes how to | Take material from | Release info | Include glossary? |
---|---|---|---|---|
OpenStack Installation Guide | Install and deploy an OpenStack cluster. |
|
Grizzly, 2013.1 |
Yes |
OpenStack Operations Guide | Design and operate OpenStack clusters. |
|
Grizzly, 2013.1 |
Yes |
OpenStack Configuration Reference | Configure OpenStack. |
|
Grizzly, 2013.1 |
Yes |
Use
Audience:
- Users of OpenStack clouds who perform tasks through the Horizon dashboard or the OpenStack command-line clients.
- Developers who develop applications on top of OpenStack by using the OpenStack APIs.
Roadmap:
- Users ramp up on cloud computing by using the Horizon dashboard and the OpenStack command-line clients.
- Then, they use the OpenStack APIs to create scalable applications.
Strategy:
- For the API Reference and the API Specifications, the plan is to use a common set of WADL files to generate the docs. Currently, the API reference page is generated from WADL files, but the API Specifications are not. This strategy will ensure that contributors must update one set of files: Both sets of docs will be generated from this single set of WADLs.
New title | Describes how to | Take material from | Release info | Include glossary? |
---|---|---|---|---|
OpenStack User Guide | Use an OpenStack cloud. |
|
Havana, 2013.1 |
Yes |
OpenStack Command Reference | Run OpenStack client commands on an OpenStack cloud. |
|
Havana, 2013.1 |
Yes |
OpenStack <project> API Specification/s | Write applications by using, review, or extend the OpenStack APIs. |
|
API vn |
Yes |
OpenStack API Reference | Write applications by using or extend OpenStack APIs. |
|
API vn |
No |
Develop
Audience: Developers who want to extend the OpenStack APIs or write applications by using the OpenStack APIs.
New title | Describes how to | Take material from | Release info | Include glossary? |
---|---|---|---|---|
OpenStack Developer Guide | Extend the OpenStack APIs or write applications by using the OpenStack APIs. |
|
API vn |
Yes |
Issues
- Lack of people to implement.