Blueprint-restructure-documentation
- Launchpad Entry: restructure-documentation
- Created: Tom Fifield
- Contributors: Diane Fleming
Contents
- 1 Summary
- 2 Audiences
- 3 Deliverables - Deployers
- 4 Design
- 5 Issues
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:
- Provide a clear roadmap through the documentation library for different audiences.
- Reduce redundancy.
- Increase usability, clarity, and consistency.
Audiences
The restructure enables these audiences to complete tasks by using the following docs:
Audience | Tasks | Docs |
---|---|---|
OpenStack cloud deployers | Install, configure, and run OpenStack clusters. |
|
OpenStack cloud users | Perform tasks in an OpenStack cloud through:
|
|
OpenStack developers | Extend the OpenStack APIs or write applications that run on top of an OpenStack cloud. |
|
Deliverables - Deployers
Audience: Deployers who want to install, configure, and run OpenStack clusters.
Product info: Havana, 2013.1
Include common glossary? Yes
OpenStack Installation Guide
Purpose
- 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.
- Include basic explanatory text for command steps, enabling first time users to understand why they are performing them.
- Introduce the OpenStack community, including how to get help.
- Exclude unusual deployment scenarios.
Source material
- 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
OpenStack Operations Guide
Purpose
- Provide opinionated direction for deployers about how to design, set up, and run OpenStack clusters.
- Include information currently in the OpenStack High Availability Guide.
- Exclude installation instructions and configuration reference information.
Source material
- OpenStack Operations Guide
- OpenStack High Availability Guide
- OpenStack <project> Administration Guide/s
- <project> devref/s
OpenStack Configuration Reference
Purpose
- 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.
Source material
- OpenStack project Administration Guide/s
- <project> devref/s
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 (web page)
- 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
New title | Describes how to | Take material from | Release info | Include glossary? |
---|---|---|---|---|
OpenStack User Guide | Use an OpenStack cloud. |
|
Havana, 2013.1 |
Yes |
OpenStack Command Reference | Run OpenStack client commands on an OpenStack cloud. |
|
Havana, 2013.1 |
Yes |
OpenStack <project> API Specification/s | Write applications by using, review, or extend the OpenStack APIs. |
|
API vn |
Yes |
OpenStack API Reference | Write applications by using or extend OpenStack APIs. |
|
API vn |
No |
Develop
Audience: Developers who want to extend the OpenStack APIs or write applications by using the OpenStack APIs.
New title | Describes how to | Take material from | Release info | Include glossary? |
---|---|---|---|---|
OpenStack Developer Guide | Extend the OpenStack APIs or write applications by using the OpenStack APIs. |
|
API vn |
Yes |
Issues
- Lack of people to implement.