Jump to: navigation, search


Revision as of 15:09, 22 September 2013 by Dfleming (talk | contribs) (OpenStack project API Reference/s)


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:

  • Provide a clear roadmap through the documentation library for different audiences: Deployers, users, and developers.
  • Reduce redundancy.
  • Increase usability, clarity, and consistency.


The restructure enables these audiences to complete tasks by using the following docs:

Audience Tasks Docs
OpenStack deployers Install, configure, and run OpenStack clusters.
  • OpenStack Installation Guide
  • OpenStack Operations Guide
  • OpenStack Configuration Reference
  • OpenStack Cloud Administrator Guide
OpenStack end and admin users Perform tasks in an OpenStack cloud through:
  • The Horizon dashboard
  • The OpenStack command-line clients
  • Directly through the OpenStack APIs - see the "OpenStack API Guide"
  • OpenStack End User Guide
  • OpenStack Admin User Guide
OpenStack contributors and application developers Extend the OpenStack APIs.

Write applications that run on top of an OpenStack cloud.

  • OpenStack API Guide
  • OpenStack API Complete Reference web pages - one page for each OpenStack project

Deliverables - Deployers

Audience: Deployers who want to install, configure, and run OpenStack clusters.
Product info: Havana, 2013.1
Include common glossary? Yes

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.

Source material

  • 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

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.

Source material

  • OpenStack Operations Guide
  • OpenStack High Availability Guide?? Or does this stay in its own book?
  • OpenStack project Administration Guide/s
  • project devref/s

OpenStack Configuration Reference


  • List configuration options available with OpenStack. Use auto-generation to generate options from the code.
  • Include configuration files, configuration options in each file, configuration extensions, and use cases for each configuration feature.
  • Exclude API parameters.

Source material

  • OpenStack project Administration Guide/s
  • project devref/s

OpenStack Cloud Administrator Guide


  • Provide guidance to day-to-day cloud administrators about how to perform administrative tasks.

Source material

  • OpenStack project Administration Guide/s
  • project devref/s

Blueprints: Blueprint - OpenStack Administration Guide, Blueprint - Modularize OpenStack Administration Guide,

Deliverables - Admin and End Users


  • Users of OpenStack clouds who perform tasks through the Horizon dashboard or the OpenStack command-line clients.
  • Beginning application developers who want to develop applications on top of OpenStack by using the OpenStack APIs.


  • Users ramp up on cloud computing by using the Horizon dashboard and the OpenStack command-line clients.
  • Then, they use the OpenStack APIs to create scalable applications.

Product info: Havana, 2013.1

Include common glossary? Yes

Blueprint: Blueprint - OpenStack User Documentation

OpenStack End User Guide


  • Explain OpenStack cloud concepts and describe how to use an OpenStack cloud.
  • Include command-line tools and credentials, and how to use Horizon dashboard.
  • Include OpenStack clients command reference as an appendix (or appendices).
  • Describe command-line clients and their subcommands and required and optional parameters.
  • Write scripts to auto-generate command and command parameters from the code.
  • Use conditional tags to generate two versions of this book: One with admin commands, and one without.
  • Exclude concepts (these go in the OpenStack User Guide) or installation instructions (these go in the OpenStack Installation Guide).
  • Exclude Cloud application architecture.

Source material

OpenStack Admin User Guide


  • Same format as End User Guide except focus on admin user tasks:
  • Manage users and projects
  • Create and manage images
  • Create and manage flavors
  • Migrate servers
  • And so on

Source material

Deliverables - Application Developers and OpenStack Contributors

Audience: People who want to extend the OpenStack APIs or write applications by using the OpenStack APIs.

Release info: API vn

Include common glossary? Yes


  • Provide an API Guide that describes API concepts, general information, and ways to access the APIs.
  • Move material currently in the API Reference/s into the WADL files that source the API Complete Reference pages.
  • Get rid of the API Reference/s.
  • Source code samples from nova code base where possible.
  • End result: One API Reference page for each project and one API Guide.

OpenStack API Guide


  • Explain API concepts and provide guidance for developers who want to extend the OpenStack APIs or write applications that run on an OpenStack cloud.

Source material

  • Python Developer Documentation
  • Language Bindings Documentation
  • Continuous Integration (CI) Developer Documentation
  • Programming OpenStack Compute API with Shell and Python
  • API Reference/s

OpenStack project API Reference/s (delete)


  • Eliminate these books.
  • Move material from these books into the WADL files that source the API Complete Reference web pages.

OpenStack API Complete Reference (web pages)


  • Provide one reference page for each project: Compute, Image Service, Identity Service, Object Storage, Networking, Orchestration, and Block Storage Service. (already implemented)
  • Source reference information from WADL files.
  • Pull material from existing API Reference/s into WADL files so everything is single-sourced from WADL files.
  • Provide developers with searchable and comprehensive Web pages that list API methods and parameters, with examples for each.
  • Exclude guidance information (this goes in the OpenStack API Guide), installation instructions, or feature descriptions that are longer than one sentence.

Source material

  • API Reference - sourced from WADL files


  • Lack of people to implement.