Difference between revisions of "Blueprint-restructure-documentation"
(→Goals) |
|||
Line 8: | Line 8: | ||
This blueprint describes a plan to restructure the OpenStack documentation to reduce redundancy and increase usability, clarity, and consistency. | 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: | ||
+ | |||
+ | {| class="wikitable" | ||
+ | |- | ||
+ | ! Title !! Audience !! Description | ||
+ | |- | ||
+ | | ''OpenStack Installation Guide'' || Deployers | ||
+ | || | ||
+ | Step-by-step instructions for how to install and deploy OpenStack clusters. | ||
+ | <br/> | ||
+ | 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. | ||
+ | * An introduction to the OpenStack community, including how to get help. | ||
+ | <br/> | ||
+ | Exclude: | ||
+ | * Unusual deployment scenarios | ||
+ | |- | ||
+ | | ''OpenStack Operations Guide'' || Deployers | ||
+ | || | ||
+ | Opinionated direction for how to design and operate OpenStack clusters. | ||
+ | <br/> | ||
+ | Exclude: | ||
+ | * Installation instructions | ||
+ | * Configuration reference information | ||
+ | |- | ||
+ | | ''OpenStack Configuration Reference'' || Deployers | ||
+ | || | ||
+ | Lists configuration options available with OpenStack. | ||
+ | <br/> | ||
+ | Include: | ||
+ | * Configuration files | ||
+ | * Configuration options in each file | ||
+ | * Configuration extensions | ||
+ | * Use cases for each configuration feature | ||
+ | <br/> | ||
+ | Exclude: | ||
+ | * API parameters | ||
+ | |- | ||
+ | | ''OpenStack User Guide'' || Users and developers | ||
+ | || | ||
+ | OpenStack cloud concepts and instructions for how to use an OpenStack cloud. | ||
+ | <p/> | ||
+ | Include: | ||
+ | * Command-line tools and credentials | ||
+ | * How to use Horizon dashboard | ||
+ | * How to create images | ||
+ | <br/> | ||
+ | Exclude: | ||
+ | * Cloud Application Architecture | ||
+ | |- | ||
+ | | ''OpenStack Command Reference'' || Users and developers | ||
+ | || | ||
+ | Command-line clients, with subcommands and required and optional parameters. | ||
+ | <br/> | ||
+ | Include: | ||
+ | * Each command-line client | ||
+ | * For each client, lists and describes subcommands and required and optional parameters | ||
+ | <br/> | ||
+ | Exclude: | ||
+ | * Concepts (these go in the ''OpenStack User Guide'') | ||
+ | * Installation instructions (these go in the ''OpenStack Installation Guide'') | ||
+ | |- | ||
+ | | ''OpenStack Developer Guide'' || Developers | ||
+ | || | ||
+ | Guidance for developing code for OpenStack. | ||
+ | |- | ||
+ | | ''OpenStack <project> API Specification'' || Developers | ||
+ | || | ||
+ | API concepts followed by descriptions of API methods and parameters, with examples for each. | ||
+ | <br/> | ||
+ | Include: | ||
+ | * Advanced guidance information | ||
+ | |- | ||
+ | | ''OpenStack API Reference'' || Developers | ||
+ | || | ||
+ | Searchable and comprehensive Web page that lists API methods and parameters, with examples for each. | ||
+ | <br/> | ||
+ | Exclude: | ||
+ | * Advanced guidance information (this goes in the ''OpenStack <project> API Specification/s'') | ||
+ | * Installation instructions | ||
+ | * Descriptions of features longer than one sentence | ||
+ | |} | ||
== Design == | == Design == | ||
Line 17: | Line 103: | ||
{| class="wikitable" | {| class="wikitable" | ||
|- | |- | ||
− | ! Planned document !! Description !! Take material from | + | ! Planned document !! Description !! Take material from !! Include glossary? |
|- | |- | ||
− | | OpenStack Installation Guide || | + | | OpenStack Installation Guide || Install and deploy an OpenStack cluster. |
|| | || | ||
* OpenStack Basic Install Guide - Ubuntu 12.04 | * OpenStack Basic Install Guide - Ubuntu 12.04 | ||
Line 30: | Line 116: | ||
Yes | Yes | ||
|- | |- | ||
− | | OpenStack Operations Guide || | + | | OpenStack Operations Guide || Design and operate OpenStack clusters. |
|| | || | ||
* OpenStack Operations Guide | * OpenStack Operations Guide | ||
Line 38: | Line 124: | ||
Yes | Yes | ||
|- | |- | ||
− | | OpenStack Configuration Reference || | + | | OpenStack Configuration Reference || Configure OpenStack. |
|| | || | ||
* OpenStack <project> Administration Guide/s | * OpenStack <project> Administration Guide/s | ||
Line 54: | Line 140: | ||
! Planned document !! Description !! Take material from !! Include glossary? | ! Planned document !! Description !! Take material from !! Include glossary? | ||
|- | |- | ||
− | | OpenStack User Guide || | + | | OpenStack User Guide || Complete user tasks on an OpenStack cloud. |
|| | || | ||
* OpenStack API Quick Start | * OpenStack API Quick Start | ||
Line 64: | Line 150: | ||
Yes | Yes | ||
|- | |- | ||
− | | OpenStack Command Reference || OpenStack client commands. | + | | OpenStack Command Reference || Run OpenStack client commands. |
|| | || | ||
* OpenStack Clients Guide | * OpenStack Clients Guide | ||
Line 80: | Line 166: | ||
! Planned document !! Description !! Take material from !! Include glossary? | ! Planned document !! Description !! Take material from !! Include glossary? | ||
|- | |- | ||
− | | OpenStack <project> API Specification || | + | | OpenStack <project> API Specification || Write applications by using, review, or extend OpenStack APIs. |
|| | || | ||
* OpenStack <project> API Dev Guides | * OpenStack <project> API Dev Guides | ||
Line 86: | Line 172: | ||
Yes | Yes | ||
|- | |- | ||
− | | OpenStack API Reference || | + | | OpenStack API Reference || Write applications by using or extend OpenStack APIs. |
|| | || | ||
* API Complete Reference | * API Complete Reference | ||
Line 92: | Line 178: | ||
No | No | ||
|- | |- | ||
− | | OpenStack Compute API Developer Guide for Shell and Python || | + | | OpenStack Compute API Developer Guide for Shell and Python || Write Python applications by using the OpenStack APIs. |
|| | || | ||
* Programming OpenStack Compute API with Shell and Python | * Programming OpenStack Compute API with Shell and Python | ||
Line 98: | Line 184: | ||
Yes | Yes | ||
|- | |- | ||
− | | OpenStack Developer Guide || | + | | OpenStack Developer Guide || Develop code for OpenStack. |
|| | || | ||
* Continuous Integration (CI) Developer Documentation | * Continuous Integration (CI) Developer Documentation | ||
Line 107: | Line 193: | ||
|} | |} | ||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
== Issues == | == Issues == |
Revision as of 17:18, 14 May 2013
- Launchpad Entry: restructure-documentation
- Created: Tom Fifield
- Contributors: Diane Fleming
Contents
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.
Goals
The restructure aims to create the following main documents with the following goals:
Title | Audience | Description |
---|---|---|
OpenStack Installation Guide | Deployers |
Step-by-step instructions for how to install and deploy OpenStack clusters.
|
OpenStack Operations Guide | Deployers |
Opinionated direction for how to design and operate OpenStack clusters.
|
OpenStack Configuration Reference | Deployers |
Lists configuration options available with OpenStack.
|
OpenStack User Guide | Users and developers |
OpenStack cloud concepts and instructions for how to use an OpenStack cloud. <p/> Include:
|
OpenStack Command Reference | Users and developers |
Command-line clients, with subcommands and required and optional parameters.
|
OpenStack Developer Guide | Developers |
Guidance for developing code for OpenStack. |
OpenStack <project> API Specification | Developers |
API concepts followed by descriptions of API methods and parameters, with examples for each.
|
OpenStack API Reference | Developers |
Searchable and comprehensive Web page that lists API methods and parameters, with examples for each.
|
Design
Install and deploy a OpenStack cloud
Audience: Deployers of OpenStack clusters
Planned document | Description | Take material from | Include glossary? |
---|---|---|---|
OpenStack Installation Guide | Install and deploy an OpenStack cluster. |
|
Yes |
OpenStack Operations Guide | Design and operate OpenStack clusters. |
|
Yes |
OpenStack Configuration Reference | Configure OpenStack. |
|
Yes |
Use an OpenStack cloud
Audience: OpenStack cloud users and developers.
Planned document | Description | Take material from | Include glossary? |
---|---|---|---|
OpenStack User Guide | Complete user tasks on an OpenStack cloud. |
|
Yes |
OpenStack Command Reference | Run OpenStack client commands. |
|
Yes |
Develop applications with or extend OpenStack APIs
Audience: Developers
Planned document | Description | Take material from | Include glossary? |
---|---|---|---|
OpenStack <project> API Specification | Write applications by using, review, or extend OpenStack APIs. |
|
Yes |
OpenStack API Reference | Write applications by using or extend OpenStack APIs. |
|
No |
OpenStack Compute API Developer Guide for Shell and Python | Write Python applications by using the OpenStack APIs. |
|
Yes |
OpenStack Developer Guide | Develop code for OpenStack. |
|
Yes |
Issues
- Lack of people to implement.