Jump to: navigation, search

Difference between revisions of "Blueprint-restructure-documentation"

m (→‎Design)
(→‎Design)
Line 13: Line 13:
 
{| class="wikitable"
 
{| class="wikitable"
 
|-
 
|-
−
! Existing document !! Planned document
+
! Audience !! Existing document !! Planned document
 
|-
 
|-
−
| OpenStack API Quick Start  || OpenStack User Guide
+
| Users || OpenStack API Quick Start  || OpenStack User Guide
 
|-
 
|-
−
| Programming OpenStack Compute API with Shell and Python  || OpenStack User Guide
+
| Users ||  Programming OpenStack Compute API with Shell and Python  || OpenStack User Guide
 
|-
 
|-
−
| API Specifications  || OpenStack User Guide
+
| Users ||  API Specifications  || OpenStack User Guide
 
|-
 
|-
−
| API Complete Reference || '''API Reference'''
+
| Developers ||  API Complete Reference || '''API Reference'''
 
|-
 
|-
−
| Basic Installation Guide for Ubuntu 12.04/12.10 (Folsom) || Installation Guide, Operations Guide
+
| Deployers ||  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) || Installation Guide, Operations Guide
+
| Deployers || 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) || Installation Guide, 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
 
|-
 
|-
−
| OpenStack Networking (Quantum) Installation || Installation Guide
+
| Deployers || OpenStack Networking (Quantum) Installation || IOpenStack Installation Guide
 
|-
 
|-
−
| Compute Administration Guide || Installation Guide, Operations Guide
+
| Administrators || Compute Administration Guide || OpenStack Installation Guide, OpenStack Operations Guide
 
|-
 
|-
−
| Network Administration Guide || Installation Guide, Operations Guide
+
| Administrators || Network Administration Guide || OpenStack Installation Guide, OpenStack Operations Guide
 
|-
 
|-
−
| Object Storage Administration Guide || Installation Guide, Operations Guide
+
| Administrators || Object Storage Administration Guide || OpenStack Installation Guide, OpenStack Operations Guide
 
|-
 
|-
−
| OpenStack Operations Guide || '''OpenStack Operations Guide'''
+
| Administrators || OpenStack Operations Guide || '''OpenStack Operations Guide'''
 
|-
 
|-
−
| Python Developer Documentation || Users Manual
+
| Developers || Python Developer Documentation || Users Manual
 
|-
 
|-
−
| Language Bindings Documentation || Users Manual
+
| Developers || Language Bindings Documentation || Users Manual
 
|-
 
|-
−
| Continuous Integration (CI) Developer Documentation || Developing OpenStack
+
| Developers || Continuous Integration (CI) Developer Documentation || Developing OpenStack
 
|-
 
|-
−
| OpenStack Clients Guide || Users Manual
+
| Users || OpenStack Clients Guide || OpenStack Command Reference
 
|-
 
|-
−
| OpenStack Glossary || All guides
+
| All || OpenStack Glossary || All guides and references
 
|-
 
|-
−
| Nova devref || Developing OpenStack
+
| Developers || Nova devref || Developing OpenStack
 
|-
 
|-
−
| Swift devref  || Developing OpenStack, Operations Guide, Installation Guide, Reference Manual, Users Manual
+
| Developers || Swift devref  || Developing OpenStack, Operations Guide, Installation Guide, Reference Manual, Users Manual
 
|-
 
|-
−
| Keystone devref  || Developing OpenStack, Operations Guide, Installation Guide, Reference Manual, Users Manual
+
| Developers || Keystone devref  || Developing OpenStack, Operations Guide, Installation Guide, Reference Manual, Users Manual
 
|-
 
|-
−
| Glance devref  || Developing OpenStack, Operations Guide, Installation Guide, Reference Manual, Users Manual
+
| Developers || Glance devref  || Developing OpenStack, Operations Guide, Installation Guide, Reference Manual, Users Manual
 
|-
 
|-
−
|  Horizon devref || Developing OpenStack, Operations Guide, Installation Guide, Reference Manual, Users Manual
+
|  Developers || Horizon devref || Developing OpenStack, Operations Guide, Installation Guide, Reference Manual, Users Manual
 
|-
 
|-
−
| Cinder devref || Developing OpenStack
+
| Developers || Cinder devref || Developing OpenStack
 
|-
 
|-
 
|}
 
|}

Revision as of 14:08, 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

Audience Existing document Planned document
Users OpenStack API Quick Start OpenStack User Guide
Users Programming OpenStack Compute API with Shell and Python OpenStack User Guide
Users API Specifications OpenStack User Guide
Developers API Complete Reference API Reference
Deployers Basic Installation Guide for Ubuntu 12.04/12.10 (Folsom) OpenStack Installation Guide, OpenStack Operations Guide
Deployers Install and Deploy Guide for Ubuntu 12.10 (Folsom) 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
Deployers OpenStack Networking (Quantum) Installation IOpenStack Installation Guide
Administrators Compute Administration Guide OpenStack Installation Guide, OpenStack Operations Guide
Administrators Network Administration Guide OpenStack Installation Guide, OpenStack Operations Guide
Administrators Object Storage Administration Guide OpenStack Installation Guide, OpenStack Operations Guide
Administrators OpenStack Operations Guide OpenStack Operations Guide
Developers Python Developer Documentation Users Manual
Developers Language Bindings Documentation Users Manual
Developers Continuous Integration (CI) Developer Documentation Developing OpenStack
Users OpenStack Clients Guide OpenStack Command Reference
All OpenStack Glossary All guides and references
Developers Nova devref Developing OpenStack
Developers Swift devref Developing OpenStack, Operations Guide, Installation Guide, Reference Manual, Users Manual
Developers Keystone devref Developing OpenStack, Operations Guide, Installation Guide, Reference Manual, Users Manual
Developers Glance devref Developing OpenStack, Operations Guide, Installation Guide, Reference Manual, Users Manual
Developers Horizon devref Developing OpenStack, Operations Guide, Installation Guide, Reference Manual, Users Manual
Developers Cinder devref Developing OpenStack


The restructure aims to create the following main documents:

- Install Guide Operations Guide Reference Manual API Reference Users Manual Developing OpenStack
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 realise
Retrieved from "https://wiki.openstack.org/w/index.php?title=Blueprint-restructure-documentation&oldid=22475"