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, OpenStack Administration Reference
|
Network Administration Guide |
OpenStack Installation Guide, OpenStack Operations Guide, OpenStack Administration Reference
|
Object Storage Administration Guide |
OpenStack Installation Guide, OpenStack Operations Guide, OpenStack Administration Reference
|
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 Clients Guide |
OpenStack User Guide
|
OpenStack Clients Guide |
OpenStack Command Reference
|
OpenStack Glossary |
All guides and references
|
Develop applications with or extend OpenStack APIs
Existing documents |
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
|
Nova devref, Swift devref, Keystone devref, Glance devref, Horizon devref, Cinder devref |
OpenStack Developer Guide, Operations Guide, Installation Guide, Administration Reference, User Guide
|
Goals
The restructure aims to create the following main documents with the following goals:
- |
Installation Guide |
Operations Guide |
Administration Reference |
API Reference |
User Guide |
Developer Guide
|
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.