Jump to: navigation, search

Blueprint-restructure-documentation

Revision as of 16:00, 14 May 2013 by Dfleming (talk | contribs) (Use an OpenStack cloud)

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

Install and deploy a OpenStack cloud

Planned document Take material from
OpenStack Installation Guide 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 OpenStack Operations Guide

OpenStack <project> Administration Guide/s
<project> devref/s

OpenStack Administration Reference OpenStack <project> Administration Guide/s

<project> devref/s

Use an OpenStack cloud

Planned document Take material from
OpenStack User Guide OpenStack API Quick Start

Python Developer Documentation
Language Bindings Documentation
OpenStack Clients Guide
<project> devref/s

include OpenStack Glossary

OpenStack Command Reference OpenStack Clients Guide

Develop applications with or extend OpenStack APIs

Planned document Take material from
OpenStack <project> API Specification OpenStack <project> API Dev Guides
OpenStack API Reference API Complete Reference
OpenStack Compute API Developer Guide for Shell and Python Programming OpenStack Compute API with Shell and Python
OpenStack Developer Guide Continuous Integration (CI) Developer Documentation

<project> devref/s

Goals

The restructure aims to create the following main documents with the following goals:

- Installation Guide Operations Guide Administration Reference API Reference User Guide Developer Guide
Audience Deployers Deployers Administrators Developers Users Developers
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 implement.