Difference between revisions of "Blueprint-restructure-documentation"
(→Summary) |
|||
(120 intermediate revisions by 4 users not shown) | |||
Line 1: | Line 1: | ||
− | + | {{ImplementedFeature}} | |
* '''Launchpad Entry''': [https://blueprints.launchpad.net/openstack-manuals/+spec/restructure-documentation restructure-documentation] | * '''Launchpad Entry''': [https://blueprints.launchpad.net/openstack-manuals/+spec/restructure-documentation restructure-documentation] | ||
* '''Created''': Tom Fifield | * '''Created''': Tom Fifield | ||
Line 7: | Line 7: | ||
The OpenStack documentation library was designed a few years ago. | The OpenStack documentation library was designed a few years ago. | ||
− | Since then, the library has grown without a specific organization. | + | Since then, the library has grown without a specific organization. Also, doc contributors have learned how users interact with it. |
− | |||
− | Also, doc contributors have learned how users interact with it. | ||
This blueprint describes a plan to restructure the OpenStack documentation to:<br /> | This blueprint describes a plan to restructure the OpenStack documentation to:<br /> | ||
− | * Provide a clear roadmap through the documentation library for different audiences. | + | * Provide a clear roadmap through the documentation library for different audiences: Deployers, users, and developers. |
* Reduce redundancy. | * Reduce redundancy. | ||
* Increase usability, clarity, and consistency. | * Increase usability, clarity, and consistency. | ||
− | == | + | == Audiences == |
− | The restructure | + | The restructure enables these audiences to complete tasks by using the following docs: |
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
{| class="wikitable" | {| class="wikitable" | ||
|- | |- | ||
− | ! | + | ! Audience !! Tasks !! Docs |
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
|- | |- | ||
− | | | + | | OpenStack deployers || Install, configure, and run OpenStack clusters. |
|| | || | ||
− | * | + | * ''OpenStack Installation Guide'' |
− | * | + | * ''OpenStack Operations Guide'' |
− | * | + | * ''OpenStack Configuration Reference'' |
+ | * ''OpenStack Cloud Administrator Guide'' | ||
|- | |- | ||
− | | | + | | OpenStack end and admin users || Perform tasks in an OpenStack cloud through: |
+ | * The Horizon dashboard | ||
+ | * The OpenStack command-line clients | ||
+ | * Directly through the OpenStack APIs - see the "OpenStack API Guide" | ||
|| | || | ||
− | * | + | * ''OpenStack End User Guide'' |
− | * | + | * ''OpenStack Admin User Guide'' |
− | |||
|- | |- | ||
− | | | + | | OpenStack contributors and application developers || Extend the OpenStack APIs.<br /> |
− | || | + | Write applications that run on top of an OpenStack cloud. |
− | + | || | |
− | + | * ''OpenStack API Guide'' | |
− | + | * ''OpenStack API Complete Reference'' web pages - one page for each OpenStack project | |
− | |||
− | || | ||
− | * | ||
− | |||
− | |||
− | |||
− | |||
− | * | ||
− | |||
− | |||
− | |||
− | |||
− | |||
|} | |} | ||
− | + | == Deliverables - Deployers == | |
− | == | + | '''Audience''': Deployers who want to install, configure, and run OpenStack clusters. <br /> |
− | === Install | + | '''Product info:''' Havana, 2013.1<br /> |
− | ''' | + | '''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.<br /><br /> | ||
+ | |||
+ | '''Source material''' | ||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
* OpenStack Basic Install Guide - Ubuntu 12.04 | * OpenStack Basic Install Guide - Ubuntu 12.04 | ||
* OpenStack Basic Install Guide - Fedora 18 | * OpenStack Basic Install Guide - Fedora 18 | ||
Line 95: | Line 67: | ||
* OpenStack Install and Deploy Manual - Red Hat | * OpenStack Install and Deploy Manual - Red Hat | ||
* OpenStack <project> Administration Guide/s | * 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.<br /><br /> | ||
+ | |||
+ | '''Source material''' | ||
+ | |||
* OpenStack Operations Guide | * OpenStack Operations Guide | ||
− | * OpenStack High Availability Guide | + | * OpenStack High Availability Guide?? Or does this stay in its own book? |
− | * OpenStack | + | * 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. | |
− | * OpenStack | + | * Exclude API parameters.<br /><br /> |
− | * | + | |
− | + | '''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.<br /><br /> | ||
+ | |||
+ | '''Source material''' | ||
+ | |||
+ | * OpenStack ''project'' Administration Guide/s | ||
+ | * ''project'' devref/s | ||
+ | |||
+ | |||
+ | '''Blueprints:''' [[Blueprint-os-admin-docs|Blueprint - OpenStack Administration Guide]], [[Blueprint-os-modularize-admin-docs|Blueprint - Modularize OpenStack Administration Guide]], | ||
− | == | + | == Deliverables - Admin and End Users == |
'''Audience''': | '''Audience''': | ||
* Users of OpenStack clouds who perform tasks through the Horizon dashboard or the OpenStack command-line clients. | * 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. |
<br /> | <br /> | ||
'''Roadmap''': | '''Roadmap''': | ||
Line 131: | Line 120: | ||
* Then, they use the OpenStack APIs to create scalable applications. | * Then, they use the OpenStack APIs to create scalable applications. | ||
<br /> | <br /> | ||
− | ''' | + | '''Product info:''' Havana, 2013.1<br /> |
− | + | ||
+ | '''Include common glossary?''' Yes <br /> | ||
+ | |||
+ | '''Blueprint:''' [[Blueprint-os-user-docs|Blueprint - OpenStack User Documentation]] | ||
+ | |||
+ | === OpenStack End User Guide (new) === | ||
+ | |||
+ | See [[Blueprint-os-user-docs|blueprint]] for details. | ||
+ | |||
+ | === OpenStack Admin User Guide (new) === | ||
+ | |||
+ | See [[Blueprint-os-user-docs|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.<br /> | ||
+ | |||
+ | '''Release info:''' API v''n''<br /> | ||
+ | |||
+ | '''Include common glossary?''' Yes<br /> | ||
+ | |||
+ | '''Strategy:''' | ||
+ | # Eliminate the existing API References. | ||
+ | # Add 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 to source the API Complete Reference pages. One web page for each OpenStack project. Source code samples from nova code base where possible. <br /> | ||
+ | |||
+ | |||
+ | End result: One API Reference page for each project and one API Guide. | ||
<br /> | <br /> | ||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | + | '''Blueprint:''' [[Blueprint-os-api-docs|Blueprint - OpenStack API Documentation]] | |
− | + | ||
− | + | === OpenStack API Guide (new) === | |
− | + | ||
− | + | See [[Blueprint-os-api-docs|blueprint]] for details. | |
− | + | ||
− | + | === OpenStack ''project'' API Reference/s (delete) === | |
− | + | ||
− | + | See [[Blueprint-os-api-docs|blueprint]] for details. | |
− | | | + | |
− | API | + | === OpenStack API Complete Reference (multiple web pages) === |
− | + | ||
− | + | See [[Blueprint-os-api-docs|blueprint]] for details. | |
− | | | + | |
− | |||
− | |||
− | |||
− | |||
[[Category:Spec]] | [[Category:Spec]] |
Latest revision as of 18:13, 15 May 2014
- 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 (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:
- Eliminate the existing API References.
- Add 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 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.