Jump to: navigation, search

Blueprint-restructure-documentation

Revision as of 13:47, 14 May 2013 by Dfleming (talk | contribs)

Summary

The OpenStack library was designed a few years ago. Since then, the library has grown without a specific organization. Also, we 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.

Design

Existing document Future document
OpenStack API Quick Start Users Manual
Programming OpenStack Compute API with Shell and Python Users Manual
API Specifications Users Manual
API Complete Reference API Reference
Basic Installation Guide for Ubuntu 12.04/12.10 (Folsom) Installation Guide, Operations Guide
Install and Deploy Guide for Ubuntu 12.10 (Folsom) Installation Guide, Operations Guide
Install and Deploy Guide for Red Hat Enterprise Linux, CentOS 6.x, or Fedora 17 (Folsom) Installation Guide, Operations Guide
OpenStack Networking (Quantum) Installation Installation Guide
Compute Administration Guide Installation Guide, Operations Guide
Network Administration Guide Installation Guide, Operations Guide
Object Storage Administration Guide Installation Guide, Operations Guide
OpenStack Operations Guide OpenStack Operations Guide
Python Developer Documentation Users Manual
Language Bindings Documentation Users Manual
Continuous Integration (CI) Developer Documentation Developing OpenStack
OpenStack Clients Guide Users Manual
OpenStack Glossary All guides
Nova devref Developing OpenStack
Swift devref Developing OpenStack, Operations Guide, Installation Guide, Reference Manual, Users Manual
Keystone devref Developing OpenStack, Operations Guide, Installation Guide, Reference Manual, Users Manual
Glance devref Developing OpenStack, Operations Guide, Installation Guide, Reference Manual, Users Manual
Horizon devref Developing OpenStack, Operations Guide, Installation Guide, Reference Manual, Users Manual
Cinder devref Developing OpenStack


The restructure considers 6 main documents.

- Install Guide Operations Guide Reference Manual API Reference Users Manual Developing OpenStack
Purpose Provide step-by-step instructions that allow result in an deployed OpenStack Cluster Provide opinionated direction on the design and operations of OpenStack clusters The definitive list of options able to be used with OpenStack The definitive list of API methods and parameters, with examples for each. Provide Application Developers all they need to understand about OpenStack to work with it. Provide the information needed to work on the code of OpenStack
Inclusions
  • 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.
-
  • Every configuration option, in every configuration file
  • Every extension
  • A description of every feature's common scenario
  • Every API method and every parameter
  • Examples for every API method
  • Commandline tools and credentials
  • How to use Horizon
  • How to make Images
Exclusions
  • Unusual deployment scenarios
  • Installation instructions
  • API parameters
  • Installation information
  • Descriptions of features > 1 sentence
  • Cloud Application Architecture

Issues

  • Lack of people to realise