Jump to: navigation, search

Difference between revisions of "Blueprint-restructure-documentation"

(→‎Install, Configure, and Run)
(→‎Goals)
Line 19: Line 19:
 
| ''OpenStack Installation Guide''  
 
| ''OpenStack Installation Guide''  
 
||  
 
||  
−
Provide step-by-step instructions for ''deployers'' about how to install, configure, and run OpenStack clusters.  
+
* Provide step-by-step instructions for ''deployers'' about how to install, configure, and run OpenStack clusters.  
−
<br/>
+
* Include:
−
Includes:  
+
:* 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.  
+
* Exclude unusual deployment scenarios.
−
<br/>
 
−
Excludes unusual deployment scenarios.
 
 
|-
 
|-
 
| ''OpenStack Operations Guide''  
 
| ''OpenStack Operations Guide''  
 
||  
 
||  
−
Provide opinionated direction for ''deployers'' about how to design, set up, and run OpenStack clusters.  
+
* Provide opinionated direction for ''deployers'' about how to design, set up, and run OpenStack clusters.  
−
<br/>
+
* Exclude installation instructions and configuration reference information.
−
Excludes installation instructions and configuration reference information.
 
 
|-
 
|-
 
| ''OpenStack Configuration Reference''  
 
| ''OpenStack Configuration Reference''  
 
||  
 
||  
−
List configuration options available with OpenStack.
+
* List configuration options available with OpenStack.
−
<br/>
+
* Include:
−
Includes:
+
:* Configuration files  
−
* Configuration files  
+
:* Configuration options in each file
−
* Configuration options in each file
+
:* Configuration extensions
−
* Configuration extensions
+
:* Use cases for each configuration feature  
−
* Use cases for each configuration feature  
+
* Exclude API parameters.
−
<br/>
 
−
Excludes API parameters.
 
 
|-
 
|-
 
| ''OpenStack User Guide''  
 
| ''OpenStack User Guide''  
 
||  
 
||  
−
Explain OpenStack cloud concepts and describe how to use an OpenStack cloud.  
+
* Explain OpenStack cloud concepts and describe how to use an OpenStack cloud.  
−
<br/>
+
* Include:
−
Includes:
+
:* Command-line tools and credentials.
−
* Command-line tools and credentials
+
:* How to use Horizon dashboard.
−
* How to use Horizon dashboard
+
:* How to create images.
−
* How to create images
+
* Exclude Cloud application architecture.
−
<br/>
 
−
Excludes Cloud application architecture.
 
 
|-
 
|-
 
| ''OpenStack Command Reference''  
 
| ''OpenStack Command Reference''  
 
||  
 
||  
−
Describe command-line clients and their subcommands and required and optional parameters.  
+
* Describe command-line clients and their subcommands and required and optional parameters.  
−
<br/>
+
* Exclude:
−
Excludes:
+
:* Concepts (these go in the ''OpenStack User Guide'').
−
* Concepts (these go in the ''OpenStack User Guide'')
+
:* Installation instructions (these go in the ''OpenStack Installation Guide'').
−
* Installation instructions (these go in the ''OpenStack Installation Guide'')
 
 
|-
 
|-
 
| ''OpenStack Developer Guide''  
 
| ''OpenStack Developer Guide''  
 
||  
 
||  
−
Describe how to develop code for OpenStack.   
+
* Describe how to develop code for OpenStack.   
 
|-
 
|-
 
| ''OpenStack <project> API Specification''  
 
| ''OpenStack <project> API Specification''  
 
||  
 
||  
−
Explains API concepts and describes API methods and parameters, with examples for each.  
+
* Explain API concepts and describe API methods and parameters, with examples for each.  
−
<br/>
+
* Include advanced guidance information.
−
Includes advanced guidance information.
 
 
|-
 
|-
 
| ''OpenStack API Reference''  
 
| ''OpenStack API Reference''  
 
||  
 
||  
−
Provide ''developers'' with a searchable and comprehensive Web page that lists API methods and parameters, with examples for each.  
+
* Provide ''developers'' with a searchable and comprehensive Web page that lists API methods and parameters, with examples for each.  
−
<br/>
+
* Exclude:
−
Excludes:
+
:* Advanced guidance information (this goes in the ''OpenStack <project> API Specification/s'').
−
* Advanced guidance information (this goes in the ''OpenStack <project> API Specification/s'').
+
:* Installation instructions.
−
* Installation instructions.
+
:* Descriptions of features longer than one sentence.
−
* Descriptions of features longer than one sentence.
 
 
|}
 
|}
  

Revision as of 17:49, 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
  • 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.
  • 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
  • Provide opinionated direction for deployers about how to design, set up, and run OpenStack clusters.
  • Exclude installation instructions and configuration reference information.
OpenStack Configuration Reference
  • List 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
  • Explain OpenStack cloud concepts and describe how to use an OpenStack cloud.
  • Include:
  • Command-line tools and credentials.
  • How to use Horizon dashboard.
  • 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).
  • 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
  • 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.
  • 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 Developer Guide Develop code for OpenStack.
  • Continuous Integration (CI) Developer Documentation
  • OpenStack Compute API Developer Guide for Shell and Python
  • <project> devref/s

Yes

Issues

  • Lack of people to implement.
Retrieved from "https://wiki.openstack.org/w/index.php?title=Blueprint-restructure-documentation&oldid=22554"