Blueprint-restructure-documentation


 * Launchpad Entry: restructure-documentation
 * Created: Tom Fifield
 * Contributors: Diane Fleming

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:


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

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

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
Blueprint:Install-with-multiple-architectures

Purpose


 * 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 Administration Guide/s
 * project devref/s

OpenStack Operations Guide
Purpose


 * 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
Purpose


 * 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
Purpose


 * 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
Audience:
 * 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.

Roadmap:
 * 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 (new)
See blueprint for details.

OpenStack Admin User Guide (new)
See blueprint for details.

Deliverables - Application Developers and OpenStack Contributors
Audience: Developers who want to extend the OpenStack APIs or write applications by using the OpenStack APIs.

Release info: API vn

Include common glossary? Yes

Strategy:
 * 1) Eliminate the existing API References.
 * 2) Add an API Guide that describes API concepts, general information, and ways to access the APIs.
 * 3) Move material currently in the API Reference/s into the WADL files to source the API Complete Reference pages. One web page for each OpenStack project. Source code samples from nova code base where possible.

End result: One API Reference page for each project and one API Guide.

Blueprint: Blueprint - OpenStack API Documentation

OpenStack API Guide (new)
See blueprint for details.

OpenStack project API Reference/s (delete)
See blueprint for details.

OpenStack API Complete Reference (multiple web pages)
See blueprint for details.