Difference between revisions of "Blueprint-restructure-documentation"

Revision as of 19:45, 14 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; basic explanatory text for command steps, enabling first time users to understand why they are performing them, and; an introduction to 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. 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.

Design

Install, Configure, and Run

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

Planned document	Describes how to	Take material from	Product info / 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 <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.

Planned document	Describes how to	Take material from	Include glossary?
OpenStack User Guide	Complete user tasks on an OpenStack cloud.	OpenStack API Quick Start Python Developer Documentation Language Bindings Documentation OpenStack Clients Guide <project> devref/s	Yes
OpenStack Command Reference	Run OpenStack client commands on an OpenStack cloud.	OpenStack Clients Guide	Yes

Develop

Audience: Developers who want to develop applications with or extend OpenStack APIs.

Planned document	Describes how to	Take material from	Include glossary?
OpenStack <project> API Specification/s	Write applications by using, review, or extend OpenStack APIs.	OpenStack <project> API Dev Guides	Yes
OpenStack API Reference	Write applications by using or extend OpenStack APIs.	API Complete Reference	No
OpenStack Developer Guide	Develop code for OpenStack.	Continuous Integration (CI) Developer Documentation OpenStack Compute API Developer Guide for Shell and Python <project> devref/s	Yes

Issues

Lack of people to implement.

@@ Line 66: / Line 66: @@
 {| class="wikitable"
 |-
-! Planned document !! Describes how to !! Take material from !! Include glossary?
+! Planned document !! Describes how to !! Take material from !! Product info / release info !! Include glossary?
 |-
 | ''OpenStack Installation Guide'' || Install and deploy an OpenStack cluster.
@@ Line 76: / Line 76: @@
 * OpenStack <project> Administration Guide/s
 * <project> devref/s
+||
+Grizzly, 2013.1
 ||
 Yes
@@ Line 84: / Line 86: @@
 * OpenStack <project> Administration Guide/s
 * <project> devref/s
+||
+Grizzly, 2013.1
 ||
 Yes
@@ Line 90: / Line 94: @@
 ||
 * OpenStack <project> Administration Guide/s
-* <project> devref/s<br/>
+* <project> devref/s
+||
+Grizzly, 2013.1
 ||
 Yes