Difference between revisions of "Blueprint-restructure-documentation"
(→Audiences and Goals) |
(→Audience) |
||
Line 12: | Line 12: | ||
The restructure provides documentation for the following audiences: | The restructure provides documentation for the following audiences: | ||
− | # '''OpenStack cloud deployers'''. To install, configure, and run OpenStack clusters, deployers | + | # '''OpenStack cloud deployers'''. To install, configure, and run OpenStack clusters, deployers use the ''OpenStack Installation Guide'', ''OpenStack Operations Guide,'' and ''OpenStack Configuration Reference''. |
− | # '''OpenStack cloud users'''. To perform tasks in an OpenStack cloud through the Horizon dashboard, the OpenStack command-line clients, or directly through the OpenStack APIs, users | + | # '''OpenStack cloud users'''. To perform tasks in an OpenStack cloud through the Horizon dashboard, the OpenStack command-line clients, or directly through the OpenStack APIs, users consult the ''OpenStack User Guide'' and ''OpenStack Command Reference''. |
− | # '''OpenStack developers'''. To extend the OpenStack APIs or write applications that run on top of an OpenStack cloud, developers | + | # '''OpenStack developers'''. To extend the OpenStack APIs or write applications that run on top of an OpenStack cloud, developers use the ''OpenStack Developer Guide'', ''OpenStack <project> API Specification/s'', and ''OpenStack API Reference'' web page.<br /> |
− | ''OpenStack <project> API Specification/s'', and ''OpenStack API Reference'' web page.<br /> | ||
== Deliverables == | == Deliverables == |
Revision as of 15:24, 15 May 2013
- Launchpad Entry: restructure-documentation
- Created: Tom Fifield
- Contributors: Diane Fleming
Contents
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.
Audience
The restructure provides documentation for the following audiences:
- OpenStack cloud deployers. To install, configure, and run OpenStack clusters, deployers use the OpenStack Installation Guide, OpenStack Operations Guide, and OpenStack Configuration Reference.
- OpenStack cloud users. To perform tasks in an OpenStack cloud through the Horizon dashboard, the OpenStack command-line clients, or directly through the OpenStack APIs, users consult the OpenStack User Guide and OpenStack Command Reference.
- OpenStack developers. To extend the OpenStack APIs or write applications that run on top of an OpenStack cloud, developers use the OpenStack Developer Guide, OpenStack <project> API Specification/s, and OpenStack API Reference web page.
Deliverables
The following table describes these deliverables:
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. |
|
Havana, 2013.1 |
Yes |
OpenStack Operations Guide | Design and operate OpenStack clusters. |
|
Havana, 2013.1 |
Yes |
OpenStack Configuration Reference | Configure OpenStack. |
|
Havana, 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.