Jump to: navigation, search

Difference between revisions of "Blueprint-restructure-documentation"

(→‎Design)
(→‎Design)
Line 17: Line 17:
 
! Current Document !! Future document
 
! Current Document !! Future document
 
|-
 
|-
−
| OpenStack API Quick Start  || ?
+
| OpenStack API Quick Start  || Users Manual
 
|-
 
|-
−
| Programming OpenStack Compute API with Shell and Python  || ?
+
| Programming OpenStack Compute API with Shell and Python  || Users Manual
 
|-
 
|-
−
| API Specifications  || ?
+
| API Specifications  || Users Manual
 
|-
 
|-
 
| API Complete Reference  || '''API Reference'''
 
| API Complete Reference  || '''API Reference'''
 
|-
 
|-
−
| Basic Installation Guide for Ubuntu 12.04/12.10 (Folsom)  || ?
+
| Basic Installation Guide for Ubuntu 12.04/12.10 (Folsom)  || Installation Guide, Operations Guide
 
|-
 
|-
−
| Install and Deploy Guide for Ubuntu 12.10 (Folsom)  || ?
+
| Install and Deploy Guide for Ubuntu 12.10 (Folsom)  || Installation Guide, Operations Guide
 
|-
 
|-
−
| Install and Deploy Guide for Red Hat Enterprise Linux, CentOS 6.x, or Fedora 17 (Folsom)  || ?
+
| Install and Deploy Guide for Red Hat Enterprise Linux, CentOS 6.x, or Fedora 17 (Folsom)  || Installation Guide, Operations Guide
 
|-
 
|-
−
| OpenStack Networking (Quantum) Installation  || ?
+
| OpenStack Networking (Quantum) Installation  || Installation Guide
 
|-
 
|-
−
| Compute Administration Guide  || ?
+
| Compute Administration Guide  || Installation Guide, Operations Guide
 
|-
 
|-
−
| Network Administration Guide  || ?
+
| Network Administration Guide  || Installation Guide, Operations Guide
 
|-
 
|-
−
| Object Storage Administration Guide || ?
+
| Object Storage Administration Guide || Installation Guide, Operations Guide
 
|-
 
|-
 
| OpenStack Operations Guide || '''OpenStack Operations Guide'''
 
| OpenStack Operations Guide || '''OpenStack Operations Guide'''
 
|-
 
|-
−
| Python Developer Documentation || ?
+
| Python Developer Documentation || Users Manual
 
|-
 
|-
−
| Language Bindings Documentation || ?
+
| Language Bindings Documentation || Users Manual
 
|-
 
|-
−
| Continuous Integration (CI) Developer Documentation || ?
+
| Continuous Integration (CI) Developer Documentation || Developing OpenStack
 
|-
 
|-
−
| OpenStack Clients Guide || ?
+
| OpenStack Clients Guide || Users Manual
 
|-
 
|-
−
| OpenStack Glossary || ?
+
| OpenStack Glossary || All guides
 
|-
 
|-
−
| Nova devref || ?
+
| Nova devref || Developing OpenStack
 
|-
 
|-
−
| Swift devref  || ?
+
| Swift devref  || Developing OpenStack, Operations Guide, Installation Guide, Reference Manual, Users Manual
 
|-
 
|-
−
| Keystone devref  || ?
+
| Keystone devref  || Developing OpenStack, Operations Guide, Installation Guide, Reference Manual, Users Manual
 
|-
 
|-
−
| Glance devref  || ?
+
| Glance devref  || Developing OpenStack, Operations Guide, Installation Guide, Reference Manual, Users Manual
 
|-
 
|-
−
|  Horizon devref || ?
+
|  Horizon devref || Developing OpenStack, Operations Guide, Installation Guide, Reference Manual, Users Manual
 
|-
 
|-
−
|
+
| Cinder devref || Developing OpenStack
 
|-
 
|-
 
|}
 
|}

Revision as of 06:44, 11 March 2013

Summary

Restructure the documentation for greatest effectiveness.

Rationale

The original documentation layout for OpenStack was designed a couple of years ago. We have created a lot of documentation, and learnt much about how our various users interact with it. We now also have a new book: the OpenStack Operations Guide.


Design

Current Document Future document
OpenStack API Quick Start Users Manual
Programming OpenStack Compute API with Shell and Python Users Manual
API Specifications Users Manual
API Complete Reference API Reference
Basic Installation Guide for Ubuntu 12.04/12.10 (Folsom) Installation Guide, Operations Guide
Install and Deploy Guide for Ubuntu 12.10 (Folsom) Installation Guide, Operations Guide
Install and Deploy Guide for Red Hat Enterprise Linux, CentOS 6.x, or Fedora 17 (Folsom) Installation Guide, Operations Guide
OpenStack Networking (Quantum) Installation Installation Guide
Compute Administration Guide Installation Guide, Operations Guide
Network Administration Guide Installation Guide, Operations Guide
Object Storage Administration Guide Installation Guide, Operations Guide
OpenStack Operations Guide OpenStack Operations Guide
Python Developer Documentation Users Manual
Language Bindings Documentation Users Manual
Continuous Integration (CI) Developer Documentation Developing OpenStack
OpenStack Clients Guide Users Manual
OpenStack Glossary All guides
Nova devref Developing OpenStack
Swift devref Developing OpenStack, Operations Guide, Installation Guide, Reference Manual, Users Manual
Keystone devref Developing OpenStack, Operations Guide, Installation Guide, Reference Manual, Users Manual
Glance devref Developing OpenStack, Operations Guide, Installation Guide, Reference Manual, Users Manual
Horizon devref Developing OpenStack, Operations Guide, Installation Guide, Reference Manual, Users Manual
Cinder devref Developing OpenStack

The restructure considers 4 main documents. Each document may have other supporting documents, such as the "High Availability Guide", which supports both the Install Guide and the Operations Guide.

- Install Guide Operations Guide Reference Manual API Reference
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.
Inclusions - -
  • 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
Exclusions
  • Unusual deployment scenarios
  • Installation instructions
  • API parameters
  • Installation information
  • Descriptions of features > 1 sentence

Issues

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