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 |
Goals
|
| OpenStack Installation Guide
|
- Provide step-by-step instructions for deployers about how to install, configure, and run OpenStack clusters.
- Include 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, and; an introduction to the OpenStack community, including how to get help.
- Exclude unusual deployment scenarios.
|
| OpenStack Operations Guide
|
- Provide opinionated direction for deployers about how to design, set up, and run OpenStack clusters.
- Exclude installation instructions and configuration reference information.
|
| OpenStack Configuration Reference
|
- List configuration options available with OpenStack.
- Include configuration files, configuration options in each file, configuration extensions, and use cases for each configuration feature.
- Exclude API parameters.
|
| OpenStack User Guide
|
- Explain OpenStack cloud concepts and describe how to use an OpenStack cloud.
- Include command-line tools and credentials, how to use Horizon dashboard, and how to create images.
- Exclude Cloud application architecture.
|
| OpenStack Command Reference
|
- Describe command-line clients and their subcommands and required and optional parameters.
- Exclude concepts (these go in the OpenStack User Guide) or installation instructions (these go in the OpenStack Installation Guide).
|
| OpenStack Developer Guide
|
- Describe how to develop code for OpenStack.
|
| OpenStack <project> API Specification
|
- Explain API concepts and describe API methods and parameters, with examples for each.
- Include advanced guidance information.
|
| OpenStack API Reference
|
- Provide developers with a searchable and comprehensive Web page that lists API methods and parameters, with examples for each.
- Exclude advanced guidance information (this goes in the OpenStack <project> API Specification/s), installation instructions, or feature descriptions that are longer than one sentence.
|
Design
Install, Configure, and Run
Audience: Deployers who want to install, configure, and run OpenStack clusters.
| Planned document |
Describes how to |
Take material from |
Include glossary?
|
| OpenStack Installation Guide |
Install and deploy an OpenStack cluster.
|
- OpenStack Basic Install Guide - Ubuntu 12.04
- OpenStack Basic Install Guide - Fedora 18
- OpenStack Install and Deploy Manual - Ubuntu
- OpenStack Install and Deploy Manual - Red Hat
- OpenStack <project> Administration Guide/s
- <project> devref/s
|
Yes
|
| OpenStack Operations Guide |
Design and operate OpenStack clusters.
|
- OpenStack Operations Guide
- OpenStack <project> Administration Guide/s
- <project> devref/s
|
Yes
|
| OpenStack Configuration Reference |
Configure OpenStack.
|
- OpenStack <project> Administration Guide/s
- <project> devref/s
|
Yes
|
Use
Audience: Users of OpenStack clouds.
| Planned document |
Describes how to |
Take material from |
Include glossary?
|
| OpenStack User Guide |
Complete user tasks on an OpenStack cloud.
|
- OpenStack API Quick Start
- Python Developer Documentation
- Language Bindings Documentation
- OpenStack Clients Guide
- <project> devref/s
|
Yes
|
| OpenStack Command Reference |
Run OpenStack client commands on an OpenStack cloud.
|
|
Yes
|
Develop
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.
|
- OpenStack <project> API Dev Guides
|
Yes
|
| OpenStack API Reference |
Write applications by using or extend OpenStack APIs.
|
|
No
|
| OpenStack Developer Guide |
Develop code for OpenStack.
|
- Continuous Integration (CI) Developer Documentation
- OpenStack Compute API Developer Guide for Shell and Python
- <project> devref/s
|
Yes
|
Issues
- Lack of people to implement.
