Difference between revisions of "Blueprint-restructure-documentation"
(→Issues) |
m (→Design) |
||
Line 10: | Line 10: | ||
== Design == | == Design == | ||
+ | |||
+ | === Install and deploy a OpenStack cloud === | ||
{| class="wikitable" | {| class="wikitable" | ||
|- | |- | ||
− | + | ! Existing document !! Planned documents | |
|- | |- | ||
− | | | + | | Basic Installation Guide for Ubuntu 12.04/12.10 (Folsom) || OpenStack Installation Guide, OpenStack Operations Guide |
|- | |- | ||
− | | | + | | Install and Deploy Guide for Ubuntu 12.10 (Folsom) || OpenStack Installation Guide, OpenStack Operations Guide |
|- | |- | ||
− | | | + | | Install and Deploy Guide for Red Hat Enterprise Linux, CentOS 6.x, or Fedora 17 (Folsom) || OpenStack Installation Guide, OpenStack Operations Guide |
|- | |- | ||
− | | | + | | OpenStack Networking (Quantum) Installation || This book goes away - redundant with material in the OpenStack Networking Administration Guide. |
|- | |- | ||
− | | | + | | Compute Administration Guide || OpenStack Installation Guide, OpenStack Operations Guide |
|- | |- | ||
− | | | + | | Network Administration Guide || OpenStack Installation Guide, OpenStack Operations Guide |
|- | |- | ||
− | | | + | | Object Storage Administration Guide || OpenStack Installation Guide, OpenStack Operations Guide |
|- | |- | ||
− | | | + | | OpenStack Operations Guide || OpenStack Operations Guide |
+ | |} | ||
+ | |||
+ | === Use an OpenStack cloud === | ||
+ | |||
+ | {| class="wikitable" | ||
|- | |- | ||
− | | | + | ! Existing documents !! Planned document |
+ | |- | ||
+ | | OpenStack API Quick Start, Python Developer Documentation, Language Bindings Documentation || OpenStack User Guide | ||
+ | |- | ||
+ | | OpenStack Clients Guide || OpenStack Command Reference | ||
+ | |- | ||
+ | |} | ||
+ | |||
+ | === Develop applications with or extend OpenStack APIs === | ||
+ | |||
+ | {| class="wikitable" | ||
|- | |- | ||
− | + | ! Existing document !! Planned document | |
|- | |- | ||
− | | | + | | API Dev Guides || OpenStack <project> API Specification |
|- | |- | ||
− | | | + | | API Complete Reference || '''API Reference''' |
|- | |- | ||
− | | | + | | Programming OpenStack Compute API with Shell and Python || OpenStack Compute API Developer Guide for Shell and Python |
|- | |- | ||
− | | | + | | Python Developer Documentation || User Guide ?? |
|- | |- | ||
− | | | + | | Language Bindings Documentation || User Guide ?? |
|- | |- | ||
− | | | + | | Continuous Integration (CI) Developer Documentation || Developer Guide |
|- | |- | ||
− | + | | OpenStack Glossary || All guides and references | |
|- | |- | ||
− | + | | Nova devref || Developer Guide | |
|- | |- | ||
− | + | | Swift devref || Developer Guide, Operations Guide, Installation Guide, Administration Reference, User Guide | |
|- | |- | ||
− | + | | Keystone devref || Developer Guide, Operations Guide, Installation Guide, Administration Reference, User Guide | |
|- | |- | ||
− | + | | Glance devref || Developer Guide, Operations Guide, Installation Guide, Administration Reference, User Guide | |
|- | |- | ||
− | | | + | | Horizon devref || Developer Guide, Operations Guide, Installation Guide, Administration Reference, User Guide |
|- | |- | ||
− | + | | Cinder devref || Developer Guide | |
|- | |- | ||
|} | |} |
Revision as of 14:44, 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
Existing document | Planned documents |
---|---|
Basic Installation Guide for Ubuntu 12.04/12.10 (Folsom) | OpenStack Installation Guide, OpenStack Operations Guide |
Install and Deploy Guide for Ubuntu 12.10 (Folsom) | OpenStack Installation Guide, OpenStack Operations Guide |
Install and Deploy Guide for Red Hat Enterprise Linux, CentOS 6.x, or Fedora 17 (Folsom) | OpenStack Installation Guide, OpenStack Operations Guide |
OpenStack Networking (Quantum) Installation | This book goes away - redundant with material in the OpenStack Networking Administration Guide. |
Compute Administration Guide | OpenStack Installation Guide, OpenStack Operations Guide |
Network Administration Guide | OpenStack Installation Guide, OpenStack Operations Guide |
Object Storage Administration Guide | OpenStack Installation Guide, OpenStack Operations Guide |
OpenStack Operations Guide | OpenStack Operations Guide |
Use an OpenStack cloud
Existing documents | Planned document |
---|---|
OpenStack API Quick Start, Python Developer Documentation, Language Bindings Documentation | OpenStack User Guide |
OpenStack Clients Guide | OpenStack Command Reference |
Develop applications with or extend OpenStack APIs
Existing document | Planned document |
---|---|
API Dev Guides | OpenStack <project> API Specification |
API Complete Reference | API Reference |
Programming OpenStack Compute API with Shell and Python | OpenStack Compute API Developer Guide for Shell and Python |
Python Developer Documentation | User Guide ?? |
Language Bindings Documentation | User Guide ?? |
Continuous Integration (CI) Developer Documentation | Developer Guide |
OpenStack Glossary | All guides and references |
Nova devref | Developer Guide |
Swift devref | Developer Guide, Operations Guide, Installation Guide, Administration Reference, User Guide |
Keystone devref | Developer Guide, Operations Guide, Installation Guide, Administration Reference, User Guide |
Glance devref | Developer Guide, Operations Guide, Installation Guide, Administration Reference, User Guide |
Horizon devref | Developer Guide, Operations Guide, Installation Guide, Administration Reference, User Guide |
Cinder devref | Developer Guide |
Goals
The restructure aims to create the following main documents:
- | OpenStack Installation Guide | OpenStack Operations Guide | OpenStack Reference | OpenStack API Reference | OpenStack User Guide | Developing OpenStack |
---|---|---|---|---|---|---|
Audience | Deployers | Deployers | Administrators | Developers | Users | Developers |
Purpose | Provide step-by-step instructions that allow result in an deployed OpenStack Cluster | Provide opinionated direction on the design and operations of OpenStack clusters | The definitive list of options able to be used with OpenStack | The definitive list of API methods and parameters, with examples for each. | Provide Application Developers all they need to understand about OpenStack to work with it. | Provide the information needed to work on the code of OpenStack |
Inclusions |
|
- |
|
|
|
|
Exclusions |
|
|
|
|
|
Issues
- Lack of people to implement.