Jump to: navigation, search

Blueprint-restructure-documentation

Revision as of 17:36, 14 May 2013 by Dfleming (talk | contribs) (→‎Goals)

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

Step-by-step instructions for deployers for how to install, configure, and run OpenStack clusters.
Includes:

  • 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.


Excludes:

  • Unusual deployment scenarios
OpenStack Operations Guide

Opinionated direction for deployers for how to design, set up, and operate OpenStack clusters.
Excludes:

  • Installation instructions
  • Configuration reference information
OpenStack Configuration Reference

Lists configuration options available with OpenStack.
Includes:

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


Excludes:

  • API parameters
OpenStack User Guide

Explains OpenStack cloud concepts and describes how to use an OpenStack cloud.
Includes:

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


Excludes:

  • Cloud Application Architecture
OpenStack Command Reference

Describes command-line clients and their subcommands and required and optional parameters.
Includes:

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


Excludes:

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

Provides guidance for developing code for OpenStack.

OpenStack <project> API Specification

Explains API concepts and describes API methods and parameters, with examples for each.
Includes:

  • Advanced guidance information
OpenStack API Reference

Provides developers with a searchable and comprehensive Web page that lists API methods and parameters, with examples for each.
Excludes:

  • Advanced guidance information (this goes in the OpenStack <project> API Specification/s)
  • Installation instructions
  • Descriptions of features 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 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 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 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.
Retrieved from "https://wiki.openstack.org/w/index.php?title=Blueprint-restructure-documentation&oldid=22545"