Jump to: navigation, search

Blueprint-restructure-documentation

Revision as of 20:48, 14 May 2013 by Dfleming (talk | contribs) (Install, Configure, and Run)

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.

Planned document 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

Grizzly, 2013.1

Yes

OpenStack Command Reference Run OpenStack client commands on an OpenStack cloud.
  • OpenStack Clients Guide

Grizzly, 2013.1

Yes

Develop

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

Planned document Describes how to Take material from Release info Include glossary?
OpenStack <project> API Specification/s Write applications by using, review, or extend the OpenStack APIs.
  • OpenStack <project> API Specification/s

API v<n>

Yes

OpenStack API Reference Write applications by using or extend OpenStack APIs.
  • API Complete Reference

API v<n>

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

API v<n>

Yes

Issues

  • Lack of people to implement.