Jump to: navigation, search

Difference between revisions of "Blueprint-restructure-documentation"

(Use)
(Goals)
Line 15: Line 15:
 
{| class="wikitable"
 
{| class="wikitable"
 
|-
 
|-
! Title !! Audience !! Goals  
+
! Title !! Goals  
 
|-
 
|-
| ''OpenStack Installation Guide'' || Deployers
+
| ''OpenStack Installation Guide''  
 
||  
 
||  
Step-by-step instructions for how to install and deploy OpenStack clusters.  
+
Step-by-step instructions for ''deployers'' for how to install, configure, and run OpenStack clusters.  
 
<br/>
 
<br/>
 
Include:  
 
Include:  
Line 29: Line 29:
 
* Unusual deployment scenarios
 
* Unusual deployment scenarios
 
|-
 
|-
| ''OpenStack Operations Guide'' || Deployers
+
| ''OpenStack Operations Guide''  
 
||  
 
||  
Opinionated direction for how to design and operate OpenStack clusters.  
+
Opinionated direction for ''deployers'' for how to design, set up, and operate OpenStack clusters.  
 
<br/>
 
<br/>
 
Exclude:   
 
Exclude:   
Line 37: Line 37:
 
* Configuration reference information
 
* Configuration reference information
 
|-
 
|-
| ''OpenStack Configuration Reference'' || Deployers
+
| ''OpenStack Configuration Reference''  
 
||  
 
||  
 
Lists configuration options available with OpenStack.
 
Lists configuration options available with OpenStack.
Line 50: Line 50:
 
* API parameters
 
* API parameters
 
|-
 
|-
| ''OpenStack User Guide'' || Users and developers
+
| ''OpenStack User Guide''  
 
||  
 
||  
OpenStack cloud concepts and instructions for how to use an OpenStack cloud.  
+
Explains OpenStack cloud concepts and describes how to use an OpenStack cloud.  
 
<p/>
 
<p/>
 
Include:
 
Include:
Line 62: Line 62:
 
* Cloud Application Architecture  
 
* Cloud Application Architecture  
 
|-
 
|-
| ''OpenStack Command Reference'' || Users and developers
+
| ''OpenStack Command Reference''  
 
||  
 
||  
Command-line clients, with subcommands and required and optional parameters.  
+
Describes command-line clients and their subcommands and required and optional parameters.  
 
<br/>
 
<br/>
 
Include:
 
Include:
Line 74: Line 74:
 
* Installation instructions (these go in the ''OpenStack Installation Guide'')
 
* Installation instructions (these go in the ''OpenStack Installation Guide'')
 
|-
 
|-
| ''OpenStack Developer Guide'' || Developers
+
| ''OpenStack Developer Guide''  
 
||  
 
||  
Guidance for developing code for OpenStack.   
+
Provides guidance for developing code for OpenStack.   
 
|-
 
|-
| ''OpenStack <project> API Specification'' || Developers
+
| ''OpenStack <project> API Specification''  
 
||  
 
||  
API concepts followed by descriptions of API methods and parameters, with examples for each.  
+
Explains API concepts and describes API methods and parameters, with examples for each.  
 
<br/>
 
<br/>
 
Include:
 
Include:
Line 87: Line 87:
 
| ''OpenStack API Reference'' || Developers  
 
| ''OpenStack API Reference'' || Developers  
 
||  
 
||  
Searchable and comprehensive Web page that lists API methods and parameters, with examples for each.  
+
Provides a searchable and comprehensive Web page that lists API methods and parameters, with examples for each.  
 
<br/>
 
<br/>
 
Exclude:
 
Exclude:

Revision as of 17:35, 14 May 2013

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

Step-by-step instructions for deployers for 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.
  • An introduction to the OpenStack community, including how to get help.


Exclude:

  • Unusual deployment scenarios
OpenStack Operations Guide

Opinionated direction for deployers for how to design, set up, and operate OpenStack clusters.
Exclude:

  • Installation instructions
  • Configuration reference information
OpenStack Configuration Reference

Lists configuration options available with OpenStack.
Include:

  • Configuration files
  • Configuration options in each file
  • Configuration extensions
  • Use cases for each configuration feature


Exclude:

  • API parameters
OpenStack User Guide

Explains OpenStack cloud concepts and describes how to use an OpenStack cloud. <p/> Include:

  • Command-line tools and credentials
  • How to use Horizon dashboard
  • How to create images


Exclude:

  • Cloud Application Architecture
OpenStack Command Reference

Describes command-line clients and their subcommands and required and optional parameters.
Include:

  • Each command-line client
  • For each client, lists and describes subcommands and required and optional parameters


Exclude:

  • Concepts (these go in the OpenStack User Guide)
  • Installation instructions (these go in the OpenStack Installation Guide)
OpenStack Developer Guide

Provides guidance for developing code for OpenStack.

OpenStack <project> API Specification

Explains API concepts and describes API methods and parameters, with examples for each.
Include:

  • Advanced guidance information
OpenStack API Reference Developers

Provides 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
  • Descriptions of features 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.
  • OpenStack Clients Guide

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.
  • API Complete Reference

No

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

Yes

OpenStack Developer Guide Develop code for OpenStack.
  • Continuous Integration (CI) Developer Documentation
  • <project> devref/s

Yes

Issues

  • Lack of people to implement.