Difference between revisions of "Blueprint-restructure-documentation"

Revision as of 14:51, 15 May 2013

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

Summary

The OpenStack documentation library was designed a few years ago. Since then, the library has grown without a specific organization. Also, doc contributors 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.

Goals

The restructure aims to create the following main documents with the following goals:

Title	Goals
OpenStack Installation Guide	Provide step-by-step instructions for deployers about how to install, configure, and run OpenStack clusters. Include easy-to-follow, lightweight, command-by-command steps for installing an OpenStack cluster of defined architecture. Include basic explanatory text for command steps, enabling first time users to understand why they are performing them. Introduce the OpenStack community, including how to get help. Exclude unusual deployment scenarios.
OpenStack Operations Guide	Provide opinionated direction for deployers about how to design, set up, and run OpenStack clusters. Include information currently in the OpenStack High Availability Guide. Exclude installation instructions and configuration reference information.
OpenStack Configuration Reference	List configuration options available with OpenStack. Include configuration files, configuration options in each file, configuration extensions, and use cases for each configuration feature. Exclude API parameters.
OpenStack User Guide	Explain OpenStack cloud concepts and describe how to use an OpenStack cloud. Include command-line tools and credentials, how to use Horizon dashboard, and how to create images. Exclude Cloud application architecture.
OpenStack Command Reference	Describe command-line clients and their subcommands and required and optional parameters. Exclude concepts (these go in the OpenStack User Guide) or installation instructions (these go in the OpenStack Installation Guide).
OpenStack Developer Guide	Describe how to develop code for OpenStack.
OpenStack <project> API Specification	Explain API concepts and describe API methods and parameters, with examples for each. Include advanced guidance information.
OpenStack API Reference	Provide developers with a searchable and comprehensive Web page that lists API methods and parameters, with examples for each. Exclude advanced guidance information (this goes in the OpenStack <project> API Specification/s), installation instructions, or feature descriptions that are longer than one sentence.

The following section details the restructure plan.

Design

Install, Configure, and Run

Audience: Deployers who want to install, configure, and run OpenStack clusters.

New title	Describes how to	Take material from	Release info	Include glossary?
OpenStack Installation Guide	Install and deploy an OpenStack cluster.	OpenStack Basic Install Guide - Ubuntu 12.04 OpenStack Basic Install Guide - Fedora 18 OpenStack Install and Deploy Manual - Ubuntu OpenStack Install and Deploy Manual - Red Hat OpenStack <project> Administration Guide/s <project> devref/s	Grizzly, 2013.1	Yes
OpenStack Operations Guide	Design and operate OpenStack clusters.	OpenStack Operations Guide OpenStack High Availability Guide OpenStack <project> Administration Guide/s <project> devref/s	Grizzly, 2013.1	Yes
OpenStack Configuration Reference	Configure OpenStack.	OpenStack <project> Administration Guide/s <project> devref/s	Grizzly, 2013.1	Yes

Use

Audience:

Users of OpenStack clouds who perform tasks through the Horizon dashboard or the OpenStack command-line clients.
Developers who develop applications on top of OpenStack by using the OpenStack APIs.

New title	Describes how to	Take material from	Release info	Include glossary?
OpenStack User Guide	Use an OpenStack cloud.	OpenStack API Quick Start Python Developer Documentation Language Bindings Documentation OpenStack Clients Guide <project> devref/s	Havana, 2013.1	Yes
OpenStack Command Reference	Run OpenStack client commands on an OpenStack cloud.	OpenStack Clients Guide	Havana, 2013.1	Yes
OpenStack <project> API Specification/s	Write applications by using, review, or extend the OpenStack APIs.	OpenStack <project> API Specification/s	API vn	Yes
OpenStack API Reference	Write applications by using or extend OpenStack APIs.	API Complete Reference	API vn	No

Develop

Audience: Developers who want to extend OpenStack.

New title	Describes how to	Take material from	Release info	Include glossary?
OpenStack Developer Guide	Develop OpenStack.	Continuous Integration (CI) Developer Documentation OpenStack Compute API Developer Guide for Shell and Python <project> devref/s	API v<n>	Yes

Issues

Lack of people to implement.

@@ Line 108: / Line 108: @@
 === Use ===
-'''Audience''': Users of OpenStack clouds, at the GUI, CLI or those who want to develop applications on top of OpenStack using the APIs.
+'''Audience''':
+* Users of OpenStack clouds who perform tasks through the Horizon dashboard or the OpenStack command-line clients.
+* Developers who develop applications on top of OpenStack by using the OpenStack APIs.
 {| class="wikitable"
@@ Line 122: / Line 124: @@
 * <''project''> devref/s
 ||
-Grizzly, 2013.1
+Havana, 2013.1
 ||
 Yes
@@ Line 130: / Line 132: @@
 * OpenStack Clients Guide
 ||
-Grizzly, 2013.1
+Havana, 2013.1
 ||
 Yes
@@ Line 138: / Line 140: @@
 * OpenStack <''project''> API Specification/s
 ||
-API v<''n''>
+API v''n''
 ||
 Yes
@@ Line 146: / Line 148: @@
 * API Complete Reference
 ||
-API v<''n''>
+API v''n''
 ||
 No