Jump to: navigation, search

Blueprint-restructure-documentation

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

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

Audience: Deployers of OpenStack clusters

Planned document Description Take material from Include glossary?
OpenStack Installation Guide Step-by-step instructions for how to 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 Opinionated direction on the design and operations of OpenStack clusters.
  • OpenStack Operations Guide
  • OpenStack <project> Administration Guide/s
  • <project> devref/s

Yes

OpenStack Configuration Reference Configuration options available with OpenStack.
  • OpenStack <project> Administration Guide/s
  • <project> devref/s

Yes

Use an OpenStack cloud

Audience: OpenStack cloud users and developers.

Planned document Description Take material from Include glossary?
OpenStack User Guide OpenStack concepts and instructions for how to use an OpenStack cloud.
  • OpenStack API Quick Start
  • Python Developer Documentation
  • Language Bindings Documentation
  • OpenStack Clients Guide
  • <project> devref/s

Yes

OpenStack Command Reference OpenStack client commands.
  • OpenStack Clients Guide

Yes

Develop applications with or extend OpenStack APIs

Audience: Developers

Planned document Description Take material from Include glossary?
OpenStack <project> API Specification OpenStack API concepts, followed by descriptions of all API methods and parameters, with examples for each.
  • OpenStack <project> API Dev Guides

Yes

OpenStack API Reference Web page that lists all API methods and parameters, with examples for each.
  • API Complete Reference

No

OpenStack Compute API Developer Guide for Shell and Python Guidance for developing OpenStack applications by using specific language bindings.
  • Programming OpenStack Compute API with Shell and Python

Yes

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

Yes

Goals

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

Title Audience Description Notes
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.

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 For each command-line client,

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

Issues

  • Lack of people to implement.
Retrieved from "https://wiki.openstack.org/w/index.php?title=Blueprint-restructure-documentation&oldid=22525"