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
|
| OpenStack Glossary |
All guides and references
|
Develop applications with or extend OpenStack APIs
| Existing document |
Planned document
|
| OpenStack <project> 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
|
| Continuous Integration (CI) Developer Documentation |
OpenStack Developer Guide
|
| OpenStack Glossary |
All guides and references
|
| Nova devref |
OpenStack Developer Guide
|
| Swift devref |
OpenStack Developer Guide, Operations Guide, Installation Guide, Administration Reference, User Guide
|
| Keystone devref |
OpenStack Developer Guide, Operations Guide, Installation Guide, Administration Reference, User Guide
|
| Glance devref |
OpenStack Developer Guide, Operations Guide, Installation Guide, Administration Reference, User Guide
|
| Horizon devref |
OpenStack Developer Guide, Operations Guide, Installation Guide, Administration Reference, User Guide
|
| Cinder devref |
OpenStack 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
|
- Easy to follow, lightweight command-by-command steps for installing an OpenStack cluster of defined architecture
- Basic explanatory text for command steps, enabling first time users to understand why they are performing them.
- An introduction to the OpenStack community, including how to get help.
|
-
|
- Every configuration option, in every configuration file
- Every extension
- A description of every feature's common scenario
|
- Every API method and every parameter
- Examples for every API method
|
- Commandline tools and credentials
- How to use Horizon
- How to make Images
|
|
| Exclusions
|
- Unusual deployment scenarios
|
- Installation instructions
|
|
- Installation information
- Descriptions of features > 1 sentence
|
- Cloud Application Architecture
|
|
Issues
- Lack of people to implement.
