Difference between revisions of "Blueprint-restructure-documentation"

Revision as of 06:37, 11 March 2013

Launchpad Entry: restructure-documentation
Created: Tom Fifield
Contributors:

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	?
Programming OpenStack Compute API with Shell and Python	?
API Specifications	?
API Complete Reference	API Reference
Basic Installation Guide for Ubuntu 12.04/12.10 (Folsom)	?
Install and Deploy Guide for Ubuntu 12.10 (Folsom)	?
Install and Deploy Guide for Red Hat Enterprise Linux, CentOS 6.x, or Fedora 17 (Folsom)	?
OpenStack Networking (Quantum) Installation	?
Compute Administration Guide	?
Network Administration Guide	?
Object Storage Administration Guide	?
OpenStack Operations Guide	OpenStack Operations Guide
Python Developer Documentation	?
Language Bindings Documentation	?
Continuous Integration (CI) Developer Documentation	?
OpenStack Clients Guide	?
OpenStack Glossary	?
Nova devref	?
Swift devref	?
Keystone devref	?
Glance devref	?
Horizon devref	?

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

@@ Line 12: / Line 12: @@
 == Design ==
+{| class="wikitable"
+|-
+! Current Document !! Future document
+|-
+| OpenStack API Quick Start  || ?
+|-
+| Programming OpenStack Compute API with Shell and Python  || ?
+|-
+| API Specifications  || ?
+|-
+| API Complete Reference  || '''API Reference'''
+|-
+| Basic Installation Guide for Ubuntu 12.04/12.10 (Folsom)  || ?
+|-
+| Install and Deploy Guide for Ubuntu 12.10 (Folsom)  || ?
+|-
+| Install and Deploy Guide for Red Hat Enterprise Linux, CentOS 6.x, or Fedora 17 (Folsom)  || ?
+|-
+| OpenStack Networking (Quantum) Installation  || ?
+|-
+| Compute Administration Guide  || ?
+|-
+| Network Administration Guide  || ?
+|-
+| Object Storage Administration Guide || ?
+|-
+| OpenStack Operations Guide || '''OpenStack Operations Guide'''
+|-
+| Python Developer Documentation || ?
+|-
+| Language Bindings Documentation || ?
+|-
+| Continuous Integration (CI) Developer Documentation || ?
+|-
+| OpenStack Clients Guide || ?
+|-
+| OpenStack Glossary || ?
+|-
+| Nova devref || ?
+|-
+| Swift devref  || ?
+|-
+| Keystone devref  || ?
+|-
+| Glance devref  || ?
+|-
+|  Horizon devref || ?
+|-
+|
+|-
+|}
 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.