Difference between revisions of "Blueprint-restructure-documentation"
(→Design) |
(→Summary) |
||
Line 5: | Line 5: | ||
== Summary == | == Summary == | ||
− | The OpenStack library was designed a few years ago. Since then, the library has grown without a specific organization. Also, | + | 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. | This blueprint describes a plan to restructure the OpenStack documentation to reduce redundancy and increase usability, clarity, and consistency. |
Revision as of 17:26, 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 | Audience | Goals |
---|---|---|
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. <p/> Include:
|
OpenStack Command Reference | Users and developers |
Command-line clients, with subcommands and required and optional parameters.
|
OpenStack Developer Guide | Developers |
Guidance for developing code for OpenStack. |
OpenStack <project> API Specification | Developers |
API concepts followed by descriptions of API methods and parameters, with examples for each.
|
OpenStack API Reference | Developers |
Searchable and comprehensive Web page that lists API methods and parameters, with examples for each.
|
Design
Audience: Deployers who want to install and deploy 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 |
Audience: Users of and developers for 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. |
|
Yes |
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.