Difference between revisions of "Blueprint-restructure-documentation"
(→OpenStack Operations Guide) |
(→OpenStack Configuration Reference) |
||
Line 85: | Line 85: | ||
=== OpenStack Configuration Reference === | === OpenStack Configuration Reference === | ||
− | + | '''Purpose''' | |
* List configuration options available with OpenStack. | * List configuration options available with OpenStack. | ||
Line 91: | Line 91: | ||
* Exclude API parameters. | * Exclude API parameters. | ||
− | + | '''Source material''' | |
* OpenStack ''project'' Administration Guide/s | * OpenStack ''project'' Administration Guide/s | ||
− | * | + | * ''project'' devref/s |
== Deliverables - Users == | == Deliverables - Users == |
Revision as of 16:49, 15 May 2013
- Launchpad Entry: restructure-documentation
- Created: Tom Fifield
- Contributors: Diane Fleming
Contents
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: Deployers, users, and developers.
- 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 deployers | Install, configure, and run OpenStack clusters. |
|
OpenStack 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
Deliverables - Users
Audience:
- Users of OpenStack clouds who perform tasks through the Horizon dashboard or the OpenStack command-line clients.
- Developers who develop applications on top of OpenStack by using the OpenStack APIs.
Roadmap:
- Users ramp up on cloud computing by using the Horizon dashboard and the OpenStack command-line clients.
- Then, they use the OpenStack APIs to create scalable applications.
OpenStack User Guide
Purpose
- 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.
Source material
- OpenStack API Quick Start
- Python Developer Documentation
- Language Bindings Documentation
- OpenStack Clients Guide
- project devref/s
OpenStack Command Reference
Purpose
- 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).
Source material
- OpenStack Clients Guide
Deliverables - Developers
Audience: Developers who want to extend the OpenStack APIs or write applications by using the OpenStack APIs.
Release info: API vn
Include common glossary? Yes
Strategy: For the API Reference and the API Specifications, the plan is to use a common set of WADL files to generate the docs. Currently, the API reference page is generated from WADL files, but the API Specifications are not. Then, both sets of docs will be generated from a single set of WADLs, and contributors must update only one set of files.
OpenStack Developer Guide
Purpose
- Explain API concepts and provide guidance for developers who want to extend the OpenStack APIs or write applications that run on an OpenStack cloud.
Source material
- Python Developer Documentation
- Language Bindings Documentation
- Continuous Integration (CI) Developer Documentation
- Programming OpenStack Compute API with Shell and Python
OpenStack project API Specification
Purpose
- Explain API concepts and describe API methods and parameters, with examples for each.
- Include advanced guidance information.
Source material
- OpenStack project API Specification/s
OpenStack API Reference (web page)
Purpose
- 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.
Source material
- API Complete Reference - sourced from WADL files
Issues
- Lack of people to implement.