Difference between revisions of "Blueprint-restructure-documentation"
(→Audience) |
(→Deliverables and Audiences) |
||
Line 21: | Line 21: | ||
! Audience !! Tasks !! Docs | ! Audience !! Tasks !! Docs | ||
|- | |- | ||
− | | | + | | OpenStack cloud deployers || Install, configure, and run OpenStack clusters. |
|| | || | ||
* ''OpenStack Installation Guide'' | * ''OpenStack Installation Guide'' | ||
Line 27: | Line 27: | ||
* ''OpenStack Configuration Reference'' | * ''OpenStack Configuration Reference'' | ||
|- | |- | ||
− | | | + | | OpenStack cloud users || Perform tasks in an OpenStack cloud through the Horizon dashboard, the OpenStack command-line clients, or directly through the OpenStack APIs. |
|| | || | ||
* ''OpenStack User Guide'' | * ''OpenStack User Guide'' | ||
* ''OpenStack Command Reference'' | * ''OpenStack Command Reference'' | ||
|- | |- | ||
− | | | + | | OpenStack developers || Extend the OpenStack APIs or write applications that run on top of an OpenStack cloud. |
|| | || | ||
* ''OpenStack Developer Guide'' | * ''OpenStack Developer Guide'' |
Revision as of 15:32, 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:
- Provide a clear roadmap through the documentation library for different audiences.
- Reduce redundancy.
- Increase usability, clarity, and consistency.
Deliverables and Audiences
The restructure provides documentation for the following audiences:
Audience | Tasks | Docs |
---|---|---|
OpenStack cloud deployers | Install, configure, and run OpenStack clusters. |
|
OpenStack cloud users | Perform tasks in an OpenStack cloud through the Horizon dashboard, the OpenStack command-line clients, or directly through the OpenStack APIs. |
|
OpenStack developers | Extend the OpenStack APIs or write applications that run on top of an OpenStack cloud. |
|
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.