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.
Blueprint: Blueprint - OpenStack API Documentation
OpenStack API Guide (new)
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 (delete)
Strategy
Eliminate these books:
- Block Storage Service API v2 Reference
- Compute API v2 and Extensions Reference
- Identity Service API v2.0 Reference
- Networking API v2.0 Reference
- Image Service API v2 Reference
- Image Service API v1 Reference
- Object Storage API v1 Reference
- Programming Compute API with Shell and Python, 1st ed.
Move material from these books into the WADL files that source the API Complete Reference web pages.
OpenStack API Complete Reference (multiple 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)
- Provide 'developers' with searchable and comprehensive Web pages that list API methods and parameters, with examples for each.
- Pull material from existing API Reference/s into WADL files so everything is single-sourced from WADL files.
- Source reference information from WADL files.
- 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.