Jump to: navigation, search

Difference between revisions of "Blueprint-restructure-documentation"

(Issues)
m (Design)
Line 10: Line 10:
  
 
== Design ==
 
== Design ==
 +
 +
=== Install and deploy a OpenStack cloud ===
  
 
{| class="wikitable"
 
{| class="wikitable"
 
|-
 
|-
! Audience !! Existing document !! Planned document
+
! Existing document !! Planned documents
 
|-
 
|-
| Users || OpenStack API Quick Start  || OpenStack User Guide
+
| Basic Installation Guide for Ubuntu 12.04/12.10 (Folsom) || OpenStack Installation Guide, OpenStack Operations Guide
 
|-
 
|-
| Users || Programming OpenStack Compute API with Shell and Python  || OpenStack User Guide
+
| Install and Deploy Guide for Ubuntu 12.10 (Folsom) || OpenStack Installation Guide, OpenStack Operations Guide
 
|-
 
|-
| Users ||  API Specifications  || OpenStack User Guide
+
| Install and Deploy Guide for Red Hat Enterprise Linux, CentOS 6.x, or Fedora 17 (Folsom) || OpenStack Installation Guide, OpenStack Operations Guide
 
|-
 
|-
| Developers || API Complete Reference ||  '''API Reference'''
+
| OpenStack Networking (Quantum) Installation || This book goes away - redundant with material in the OpenStack Networking Administration Guide.
 
|-
 
|-
| Deployers ||  Basic Installation Guide for Ubuntu 12.04/12.10 (Folsom) || OpenStack Installation Guide, OpenStack Operations Guide
+
| Compute Administration Guide || OpenStack Installation Guide, OpenStack Operations Guide
 
|-
 
|-
| Deployers || Install and Deploy Guide for Ubuntu 12.10 (Folsom) || OpenStack Installation Guide, OpenStack Operations Guide
+
| Network Administration Guide || OpenStack Installation Guide, OpenStack Operations Guide
 
|-
 
|-
| Deployers || Install and Deploy Guide for Red Hat Enterprise Linux, CentOS 6.x, or Fedora 17 (Folsom) || OpenStack Installation Guide, OpenStack Operations Guide
+
| Object Storage Administration Guide || OpenStack Installation Guide, OpenStack Operations Guide
 
|-
 
|-
| Deployers || OpenStack Networking (Quantum) Installation || OpenStack Installation Guide
+
| OpenStack Operations Guide || OpenStack Operations Guide
 +
|}
 +
 
 +
=== Use an OpenStack cloud ===
 +
 
 +
{| class="wikitable"
 
|-
 
|-
| Administrators || Compute Administration Guide || OpenStack Installation Guide, OpenStack Operations Guide
+
! Existing documents !! Planned document
 +
|-
 +
| OpenStack API Quick Start, Python Developer Documentation, Language Bindings Documentation  || OpenStack User Guide
 +
|-
 +
| OpenStack Clients Guide || OpenStack Command Reference
 +
|-
 +
|}
 +
 
 +
=== Develop applications with or extend OpenStack APIs ===
 +
 
 +
{| class="wikitable"
 
|-
 
|-
| Administrators || Network Administration Guide || OpenStack Installation Guide, OpenStack Operations Guide
+
! Existing document !! Planned document
 
|-
 
|-
| Administrators || Object Storage Administration Guide || OpenStack Installation Guide, OpenStack Operations Guide
+
| API Dev Guides  || OpenStack <project> API Specification
 
|-
 
|-
| Administrators || OpenStack Operations Guide || '''OpenStack Operations Guide'''
+
| API Complete Reference || '''API Reference'''
 
|-
 
|-
| Developers || Python Developer Documentation || Users Manual
+
| Programming OpenStack Compute API with Shell and Python  || OpenStack Compute API Developer Guide for Shell and Python
 
|-
 
|-
| Developers || Language Bindings Documentation || Users Manual
+
| Python Developer Documentation || User Guide ??
 
|-
 
|-
| Developers || Continuous Integration (CI) Developer Documentation || Developing OpenStack
+
| Language Bindings Documentation || User Guide ??
 
|-
 
|-
| Users || OpenStack Clients Guide || OpenStack Command Reference
+
| Continuous Integration (CI) Developer Documentation || Developer Guide
 
|-
 
|-
| All || OpenStack Glossary || All guides and references
+
| OpenStack Glossary || All guides and references
 
|-
 
|-
| Developers || Nova devref || Developing OpenStack
+
| Nova devref || Developer Guide
 
|-
 
|-
| Developers || Swift devref  || Developing OpenStack, Operations Guide, Installation Guide, Reference Manual, Users Manual
+
| Swift devref  || Developer Guide, Operations Guide, Installation Guide, Administration Reference, User Guide
 
|-
 
|-
| Developers || Keystone devref  || Developing OpenStack, Operations Guide, Installation Guide, Reference Manual, Users Manual
+
| Keystone devref  || Developer Guide, Operations Guide, Installation Guide, Administration Reference, User Guide
 
|-
 
|-
| Developers || Glance devref  || Developing OpenStack, Operations Guide, Installation Guide, Reference Manual, Users Manual
+
| Glance devref  || Developer Guide, Operations Guide, Installation Guide, Administration Reference, User Guide
 
|-
 
|-
Developers || Horizon devref || Developing OpenStack, Operations Guide, Installation Guide, Reference Manual, Users Manual
+
|  Horizon devref || Developer Guide, Operations Guide, Installation Guide, Administration Reference, User Guide
 
|-
 
|-
| Developers || Cinder devref || Developing OpenStack
+
| Cinder devref || Developer Guide
 
|-
 
|-
 
|}
 
|}

Revision as of 14:44, 14 May 2013

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

Existing document Planned documents
Basic Installation Guide for Ubuntu 12.04/12.10 (Folsom) OpenStack Installation Guide, OpenStack Operations Guide
Install and Deploy Guide for Ubuntu 12.10 (Folsom) OpenStack Installation Guide, OpenStack Operations Guide
Install and Deploy Guide for Red Hat Enterprise Linux, CentOS 6.x, or Fedora 17 (Folsom) OpenStack Installation Guide, OpenStack Operations Guide
OpenStack Networking (Quantum) Installation This book goes away - redundant with material in the OpenStack Networking Administration Guide.
Compute Administration Guide OpenStack Installation Guide, OpenStack Operations Guide
Network Administration Guide OpenStack Installation Guide, OpenStack Operations Guide
Object Storage Administration Guide OpenStack Installation Guide, OpenStack Operations Guide
OpenStack Operations Guide OpenStack Operations Guide

Use an OpenStack cloud

Existing documents Planned document
OpenStack API Quick Start, Python Developer Documentation, Language Bindings Documentation OpenStack User Guide
OpenStack Clients Guide OpenStack Command Reference

Develop applications with or extend OpenStack APIs

Existing document Planned document
API Dev Guides OpenStack <project> API Specification
API Complete Reference API Reference
Programming OpenStack Compute API with Shell and Python OpenStack Compute API Developer Guide for Shell and Python
Python Developer Documentation User Guide ??
Language Bindings Documentation User Guide ??
Continuous Integration (CI) Developer Documentation Developer Guide
OpenStack Glossary All guides and references
Nova devref Developer Guide
Swift devref Developer Guide, Operations Guide, Installation Guide, Administration Reference, User Guide
Keystone devref Developer Guide, Operations Guide, Installation Guide, Administration Reference, User Guide
Glance devref Developer Guide, Operations Guide, Installation Guide, Administration Reference, User Guide
Horizon devref Developer Guide, Operations Guide, Installation Guide, Administration Reference, User Guide
Cinder devref Developer Guide

Goals

The restructure aims to create the following main documents:

- OpenStack Installation Guide OpenStack Operations Guide OpenStack Reference OpenStack API Reference OpenStack User Guide Developing OpenStack
Audience Deployers Deployers Administrators Developers Users Developers
Purpose Provide step-by-step instructions that allow result in an deployed OpenStack Cluster Provide opinionated direction on the design and operations of OpenStack clusters The definitive list of options able to be used with OpenStack The definitive list of API methods and parameters, with examples for each. Provide Application Developers all they need to understand about OpenStack to work with it. Provide the information needed to work on the code of OpenStack
Inclusions
  • 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.
-
  • Every configuration option, in every configuration file
  • Every extension
  • A description of every feature's common scenario
  • Every API method and every parameter
  • Examples for every API method
  • Commandline tools and credentials
  • How to use Horizon
  • How to make Images
Exclusions
  • Unusual deployment scenarios
  • Installation instructions
  • API parameters
  • Installation information
  • Descriptions of features > 1 sentence
  • Cloud Application Architecture

Issues

  • Lack of people to implement.