Difference between revisions of "Blueprint-restructure-documentation"
(→Develop applications with or extend OpenStack APIs) |
(→Goals) |
||
| Line 93: | Line 93: | ||
{| class="wikitable" | {| class="wikitable" | ||
|- | |- | ||
| − | ! | + | ! Title !! Audience !! Description !! Include !! Exclude |
|- | |- | ||
| − | | | + | | ''OpenStack Installation Guide'' || Deployers || Step-by-step instructions for how to install and deploy OpenStack clusters. || |
| − | |||
| − | || Deployers | ||
| − | || | ||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | || | ||
* Easy to follow, lightweight command-by-command steps for installing an OpenStack cluster of defined architecture | * 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. | * 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. | + | * An introduction to the OpenStack community, including how to get help. |
| − | |||
|| | || | ||
| − | * | + | * Unusual deployment scenarios |
| − | + | |- | |
| − | + | | ''OpenStack Operations Guide'' || Deployers || Opinionated direction for how to design and operate OpenStack clusters. || - | |
|| | || | ||
| − | * | + | * Installation instructions |
| − | * | + | * Configuration reference information |
| + | |- | ||
| + | | ''OpenStack Configuration Reference'' || Deployers || Lists configuration options available with OpenStack. | ||
|| | || | ||
| − | * | + | * Configuration files |
| − | * | + | * Configuration options in each file |
| − | * | + | * Configuration extensions |
| + | * Use cases for each configuration feature | ||
|| | || | ||
| + | * API parameters | ||
|- | |- | ||
| − | | | + | | ''OpenStack User Guide'' || Users and developers || OpenStack cloud concepts and instructions for how to use an OpenStack cloud. |
|| | || | ||
| − | * | + | * Command-line tools and credentials |
| + | * How to use Horizon dashboard | ||
| + | * How to create images | ||
|| | || | ||
| − | * | + | * Cloud Application Architecture |
| + | |- | ||
| + | | ''OpenStack Command Reference'' || Users and developers || For each command-line client, | ||
| + | || | ||
| + | * Describes each command-line client | ||
| + | * For each client, lists and describes subcommands and required and optional parameters | ||
|| | || | ||
| − | * API parameters | + | * Concepts (these go in the ''OpenStack User Guide'') |
| − | || | + | * Installation instructions (these go in the ''OpenStack Installation Guide'') |
| − | + | |- | |
| − | + | | ''OpenStack Developer Guide'' || Developers || Example || Example | |
| − | || | + | |- |
| − | + | | ''OpenStack <project> API Specification'' || Developers || API concepts followed by descriptions of API methods and parameters, with examples for each. || Example | |
| + | |- | ||
| + | | ''OpenStack API Reference'' || Developers || Searchable and comprehensive Web page that lists API methods and parameters, with examples for each. | ||
| + | || | ||
| + | - | ||
|| | || | ||
| + | * Advanced guidance information (this goes in the ''OpenStack <project> API Specification/s'') | ||
| + | * Installation instructions | ||
| + | * Descriptions of features that are longer than one sentence | ||
|} | |} | ||
Revision as of 16:49, 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.
Design
Install and deploy a OpenStack cloud
Audience: Deployers of OpenStack clusters
| Planned document | Description | Take material from |
|---|---|---|
| OpenStack Installation Guide | Step-by-step instructions for how to install and deploy an OpenStack cluster. | OpenStack Basic Install Guide - Ubuntu 12.04 OpenStack Basic Install Guide - Fedora 18 |
| OpenStack Operations Guide | Opinionated direction on the design and operations of OpenStack clusters. | OpenStack Operations Guide OpenStack <project> Administration Guide/s |
| OpenStack Administration Reference | Configuration options available with OpenStack. | OpenStack <project> Administration Guide/s <project> devref/s |
Use an OpenStack cloud
Audience: OpenStack cloud users and developers.
| Planned document | Description | Take material from |
|---|---|---|
| OpenStack User Guide | OpenStack concepts and instructions for how to use an OpenStack cloud. | OpenStack API Quick Start Python Developer Documentation |
| OpenStack Command Reference | OpenStack client commands. | OpenStack Clients Guide
|
Develop applications with or extend OpenStack APIs
Audience: Developers
| Planned document | Description | Take material from |
|---|---|---|
| OpenStack <project> API Specification | OpenStack API concepts, followed by descriptions of all API methods and parameters, with examples for each. | OpenStack <project> API Dev Guides
|
| OpenStack API Reference | Web page that lists all API methods and parameters, with examples for each. | API Complete Reference |
| OpenStack Compute API Developer Guide for Shell and Python | Guidance for developing OpenStack applications by using specific language bindings. | Programming OpenStack Compute API with Shell and Python
|
| OpenStack Developer Guide | Guidance for developing code for OpenStack. | Continuous Integration (CI) Developer Documentation <project> devref/s |
Goals
The restructure aims to create the following main documents with the following goals:
| Title | Audience | Description | Include | Exclude |
|---|---|---|---|---|
| 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. |
|
|
| OpenStack Command Reference | Users and developers | For each command-line client, |
|
|
| OpenStack Developer Guide | Developers | Example | Example | |
| OpenStack <project> API Specification | Developers | API concepts followed by descriptions of API methods and parameters, with examples for each. | Example | |
| OpenStack API Reference | Developers | Searchable and comprehensive Web page that lists API methods and parameters, with examples for each. |
- |
|
Issues
- Lack of people to implement.
