Difference between revisions of "Blueprint-restructure-documentation"

Revision as of 14:47, 14 May 2013

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

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
OpenStack <project> 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
Continuous Integration (CI) Developer Documentation	OpenStack Developer Guide
OpenStack Glossary	All guides and references
Nova devref	OpenStack Developer Guide
Swift devref	OpenStack Developer Guide, Operations Guide, Installation Guide, Administration Reference, User Guide
Keystone devref	OpenStack Developer Guide, Operations Guide, Installation Guide, Administration Reference, User Guide
Glance devref	OpenStack Developer Guide, Operations Guide, Installation Guide, Administration Reference, User Guide
Horizon devref	OpenStack Developer Guide, Operations Guide, Installation Guide, Administration Reference, User Guide
Cinder devref	OpenStack 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.

@@ Line 52: / Line 52: @@
 ! Existing document !! Planned document
 |-
-| API Dev Guides  || OpenStack <project> API Specification
+| OpenStack <project> API Dev Guides  || OpenStack <project> API Specification
 |-
-| API Complete Reference ||  '''API Reference'''
+| 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 ??
+| Continuous Integration (CI) Developer Documentation || OpenStack Developer Guide
-|-
-| Language Bindings Documentation || User Guide ??
-|-
-| Continuous Integration (CI) Developer Documentation || Developer Guide
 |-
 | OpenStack Glossary || All guides and references
 |-
-| Nova devref || Developer Guide
+| Nova devref || OpenStack Developer Guide
 |-
-| Swift devref  || Developer Guide, Operations Guide, Installation Guide, Administration Reference, User Guide
+| Swift devref  || OpenStack Developer Guide, Operations Guide, Installation Guide, Administration Reference, User Guide
 |-
-| Keystone devref  || Developer Guide, Operations Guide, Installation Guide, Administration Reference, User Guide
+| Keystone devref  || OpenStack Developer Guide, Operations Guide, Installation Guide, Administration Reference, User Guide
 |-
-| Glance devref  || Developer Guide, Operations Guide, Installation Guide, Administration Reference, User Guide
+| Glance devref  || OpenStack Developer Guide, Operations Guide, Installation Guide, Administration Reference, User Guide
 |-
-|  Horizon devref || Developer Guide, Operations Guide, Installation Guide, Administration Reference, User Guide
+|  Horizon devref || OpenStack Developer Guide, Operations Guide, Installation Guide, Administration Reference, User Guide
 |-
-| Cinder devref || Developer Guide
+| Cinder devref || OpenStack Developer Guide
 |-
 |}