Blueprint-restructure-documentation
- Launchpad Entry: restructure-documentation
- Created: Tom Fifield
- Contributors: Diane Fleming
Contents
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:
| Audience | Tasks | Docs |
|---|---|---|
| OpenStack deployers | Install, configure, and run OpenStack clusters. |
|
| OpenStack end and admin users | Perform tasks in an OpenStack cloud through:
|
|
| OpenStack contributors and application developers | Extend the OpenStack APIs. Write applications that run on top of an OpenStack cloud. |
|
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 <project> 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
Purpose
- 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 API Quick Start
- Python Developer Documentation
- Language Bindings Documentation
- OpenStack Clients Guide
- OpenStack Administration Guides
- OpenStack API Specifications
- Programming OpenStack Compute API with Shell and Python
- OpenStack Clients Guide
OpenStack Admin User Guide
Purpose
- 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
- OpenStack API Quick Start
- Python Developer Documentation
- Language Bindings Documentation
- OpenStack Clients Guide
- OpenStack Administration Guides
- OpenStack API Specifications
- Programming OpenStack Compute API with Shell and Python
- OpenStack Clients Guide
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
Strategy:
- 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
Purpose
- 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
Strategy
- 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)
Purpose
- 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
Issues
- Lack of people to implement.
