Difference between revisions of "Obsolete:User-guide--blueprint"
Line 1: | Line 1: | ||
+ | * '''Launchpad Entry''': [https://blueprints.launchpad.net/openstack-manuals/+spec/restructure-documentation restructure-documentation] | ||
+ | * '''Created''': Diane Fleming | ||
+ | * '''Contributors''': | ||
+ | |||
+ | == 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:<br /> | ||
+ | |||
+ | * 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: | ||
+ | {| class="wikitable" | ||
+ | |- | ||
+ | ! Audience !! Tasks !! Docs | ||
+ | |- | ||
+ | | OpenStack deployers || Install, configure, and run OpenStack clusters. | ||
+ | || | ||
+ | * ''OpenStack Installation Guide'' | ||
+ | * ''OpenStack Operations Guide'' | ||
+ | * ''OpenStack Configuration Reference'' | ||
+ | |- | ||
+ | | OpenStack users || Perform tasks in an OpenStack cloud through: | ||
+ | * The Horizon dashboard | ||
+ | * The OpenStack command-line clients | ||
+ | * Directly through the OpenStack APIs | ||
+ | || | ||
+ | * ''OpenStack User Guide'' | ||
+ | * ''OpenStack Command Reference'' | ||
+ | |- | ||
+ | | OpenStack developers || Extend the OpenStack APIs.<br /> | ||
+ | Write applications that run on top of an OpenStack cloud. | ||
+ | || | ||
+ | * ''OpenStack Developer Guide'' | ||
+ | * ''OpenStack <project> API Specification/s'' | ||
+ | * ''OpenStack API Reference'' web page | ||
+ | |} | ||
+ | |||
+ | |||
+ | == Deliverables - Users == | ||
+ | '''Audience''': | ||
+ | * Users of OpenStack clouds who perform tasks through the Horizon dashboard or the OpenStack command-line clients. | ||
+ | * Developers who develop applications on top of OpenStack by using the OpenStack APIs. | ||
+ | <br /> | ||
+ | '''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. | ||
+ | <br /> | ||
+ | '''Product info:''' Havana, 2013.1<br /> | ||
+ | |||
+ | '''Include common glossary?''' Yes <br /> | ||
+ | |||
+ | === OpenStack User Guide === | ||
+ | |||
+ | '''Purpose''' | ||
+ | |||
+ | * Explain OpenStack cloud concepts and describe how to use an OpenStack cloud. | ||
+ | * Include command-line tools and credentials, how to use Horizon dashboard, and how to create images. | ||
+ | * Exclude Cloud application architecture.<br /><br /> | ||
+ | |||
+ | '''Source material''' | ||
+ | |||
+ | * OpenStack API Quick Start | ||
+ | * Python Developer Documentation | ||
+ | * Language Bindings Documentation | ||
+ | * OpenStack Clients Guide | ||
+ | * ''project'' devref/s | ||
+ | |||
+ | === OpenStack Command Reference === | ||
+ | |||
+ | '''Purpose''' | ||
+ | |||
+ | * 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'').<br /><br /> | ||
+ | |||
+ | '''Source material''' | ||
+ | |||
+ | * OpenStack Clients Guide | ||
== OpenStack User Guide - Blueprint == | == OpenStack User Guide - Blueprint == | ||
Revision as of 15:38, 16 May 2013
- Launchpad Entry: restructure-documentation
- Created: Diane Fleming
- Contributors:
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 users | Perform tasks in an OpenStack cloud through:
|
|
OpenStack developers | Extend the OpenStack APIs. Write applications that run on top of an OpenStack cloud. |
|
Deliverables - Users
Audience:
- Users of OpenStack clouds who perform tasks through the Horizon dashboard or the OpenStack command-line clients.
- Developers who 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
OpenStack User Guide
Purpose
- Explain OpenStack cloud concepts and describe how to use an OpenStack cloud.
- Include command-line tools and credentials, how to use Horizon dashboard, and how to create images.
- Exclude Cloud application architecture.
Source material
- OpenStack API Quick Start
- Python Developer Documentation
- Language Bindings Documentation
- OpenStack Clients Guide
- project devref/s
OpenStack Command Reference
Purpose
- 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).
Source material
- OpenStack Clients Guide
OpenStack User Guide - Blueprint
WORK-IN-PROGRESS...
OpenStack Cloud Concepts
Describe the main concepts that a user needs to understand to use the cloud. Authentication/Identity service http://www.openstack.org/software/openstack-shared-services/ Images, Image service What’s an image? What’s a snapshot? http://www.openstack.org/software/openstack-shared-services/ Servers What is a virtual machine? A hypervisor? A server personality? What does it mean to boot a server? http://www.openstack.org/software/openstack-compute/
Security groups http://www.openstack.org/software/openstack-compute/ Floating IP addresses Console log Object and block storage http://www.openstack.org/software/openstack-storage/ Networking http://www.openstack.org/software/openstack-networking/ Dashboard, command-line clients, APIs, extensions How to Interact with an OpenStack Cloud Describe ways you can interact with a cloud: OpenStack Command-line Clients OpenStack APIs Talk about ways to use the APIs – cURL? SDKs? Language bindings? Horizon Dashboard http://www.openstack.org/software/openstack-dashboard/
Common User Tasks
Boot, list, and delete servers Configure VNC Attach and detach volumes Create, list, and delete images Load-balance xx
Tutorials
Provide tutorials for various use cases. Use different methods in each tutorial so user gets an idea of what’s possible.
Authenticate
Method: cURL commands with embedded API
Run Your Elastic Web Application on Your Cloud
Method: nova client Set up a user, get images for your application servers, spin up server instances, install Wordpress and its dependencies. http://docs.openstack.org/grizzly/openstack-compute/admin/content/running-elastic-web-app-cloud.html
Store Large Photos or Videos in Your Cloud
Method: swift client and Cyberduck application Set up secure access to OpenStack Object Storage, configure Cyberduck to connect to OpenStack Object Storage, and copy files to the cloud. http://docs.openstack.org/grizzly/openstack-object-storage/admin/content/storing-large-photos-or-videos-on-the-cloud.html
Booting Listing Deleting/Terminating Instance Console access About console log Configuring VNC How do I attach a volume?
(Details on doing these actions in user guide)
Attach/Detach volumes How do I save a running instance to an image? Snapshots