Jump to: navigation, search

Blueprint-restructure-documentation

Revision as of 17:28, 14 May 2013 by Dfleming (talk | contribs) (Design)

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 Audience Goals
OpenStack Installation Guide Deployers

Step-by-step instructions for how to install and deploy 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.
  • An introduction to the OpenStack community, including how to get help.


Exclude:

  • Unusual deployment scenarios
OpenStack Operations Guide Deployers

Opinionated direction for how to design and operate OpenStack clusters.
Exclude:

  • Installation instructions
  • Configuration reference information
OpenStack Configuration Reference Deployers

Lists configuration options available with OpenStack.
Include:

  • Configuration files
  • Configuration options in each file
  • Configuration extensions
  • Use cases for each configuration feature


Exclude:

  • API parameters
OpenStack User Guide Users and developers

OpenStack cloud concepts and instructions for how to use an OpenStack cloud. <p/> Include:

  • Command-line tools and credentials
  • How to use Horizon dashboard
  • How to create images


Exclude:

  • Cloud Application Architecture
OpenStack Command Reference Users and developers

Command-line clients, with subcommands and required and optional parameters.
Include:

  • Each command-line client
  • For each client, lists and describes subcommands and required and optional parameters


Exclude:

  • Concepts (these go in the OpenStack User Guide)
  • Installation instructions (these go in the OpenStack Installation Guide)
OpenStack Developer Guide Developers

Guidance for developing code for OpenStack.

OpenStack <project> API Specification Developers

API concepts followed by descriptions of API methods and parameters, with examples for each.
Include:

  • Advanced guidance information
OpenStack API Reference Developers

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
  • Descriptions of features longer than one sentence

Design

Install and Deploy

Audience: Deployers who want to install and deploy OpenStack clusters.

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

Yes

OpenStack Operations Guide Design and operate OpenStack clusters.
  • OpenStack Operations Guide
  • OpenStack <project> Administration Guide/s
  • <project> devref/s

Yes

OpenStack Configuration Reference Configure OpenStack.
  • OpenStack <project> Administration Guide/s
  • <project> devref/s

Yes

Use

Audience: Users of and developers for 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.
  • 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 Compute API Developer Guide for Shell and Python Write Python applications by using the OpenStack APIs.
  • Programming OpenStack Compute API with Shell and Python

Yes

OpenStack Developer Guide Develop code for OpenStack.
  • Continuous Integration (CI) Developer Documentation
  • <project> devref/s

Yes

Issues

  • Lack of people to implement.