DocImprovementsSpec
- Launchpad Entry: https://blueprints.launchpad.net/openstack-devel/+spec/bexar-doc-enhancements
- Created: 2010-11-29
- Contributors: AnneGentle
Contents
Summary
Efforts to produce pro-level community-based documentation.
Release Note
OpenStack strives for professional-level documentation created collaboratively with contributors from around the world. With this release of OpenStack, we want to provide a central page for documentation as well as indicators of official and tested tutorials and documentation pages.
Rationale
Documentation helps bring new developers and deployers onboard and should make their OpenStack adoption process smooth. Documentation should provide a good starting point as well as help support people as they gain expertise in open source cloud computing.
User stories
As a doc reader, I want to view content in an easy-to-understand, predictable, organized, browseable manner so that I can go through the content at my own pace from any desired entry point.
As a doc writer, I want to write content in such a way that it can fit into a content collection so that my writing efforts result in readable material for users.
As a doc writer and reader, OpenStack documentation to be connected to a larger set of documentation deliverables that could be offered as a PDF or similar portable offline downloadable collection.
As a doc translator, I want to offer non-English content for both writers and readers of another language such as Japanese.
Assumptions
The OpenStack documentation set already consists of three main sites - the wiki, and the developer documentation sites.
Design
This section describes the main subprojects that comprise the design of this implementation.
Docs site
OpenStack needs a central docs.openstack.org site that curates the content from various other sources and gives a good user experience upon landing on it. My goal is to implement this in time for Bexar (February).
Official docs
OpenStack needs a way to indicate that a page or site as "official OpenStack documentation" meaning that it is as accurate as we can get it and the procedures have been tested. Again I'd mark this for Bexar.
Versioning documentation
We are taking small steps towards a frozen release page/site. For example, you could go to http://swift.openstack.org/1.0/ and get a frozen-in-time site with the developer documentation from the 1.0 release. We can get this done in time for Bexar.
Man pages
We need man pages created for nova-manage, nova-compute, and nova-networking. The nova-manage man page is now in the builds but needs editing. It is sourced in doc/source/man from RST files and gets built with the Sphinx docs. This could be done for Bexar.
Tutorials
Now that we have virtual boxes and stack on a stick in progress, we need tutorials that are meaningful and simple enough to step through while still giving an impressive demonstration of the power of OpenStack clouds. Here are some ideas for tutorials:
1) Create a LAMP stack for a web application like WordPress - demonstrate connectivity between virtual machines, describe how to scale as your blog gets super popular (hey, we can dream, right?) 2) Build your own CDN to serve video content 3) Academic calculations where you spin up 10 machines for a Mathematica project only for a day or so 4) Create a news reader application using AMPQ/RabbitMQ
I think we could have one solid, tested tutorial done in time for Bexar with the remaining set for the Cactus release. Any thoughts on how to prioritize these tutorials? Which would be in highest demand?
Glance docs
With the Glance implementation still ongoing for Bexar, we need to plan for install and integration docs with the Bexar release. These docs do not need their own subdomain of openstack.org but can reside in nova.openstack.org.
Localization
The increasing interest in OpenStack in other countries requires systems that enables contributors to translate existing English docs OR create documentation in their native language.
Implementation
Task: Create a docs.openstack.org site. See WebContentRequirements for a list of requirements and possible implementation tools.
Task: Create a badge that indicates "official documentation" from OpenStack.
Task: The swift.openstack.org/1.0/ site is complete except for the version number in the link in the upper left corner. Fix that link.
Task: Create a div that links to the most recent documentation from the swift /1.0 site.
Task: Create a nova.openstack.org/2010.1/ site.
Task: Create a similiar div for the nova/ 2010.1 site that links to the most recent documentation.
Task: Create a man page for nova-manage. Done, but it needs testing.
Task: Create a tutorial for WordPress optimization and scaling. Work with Martin Lanner to provide information about memcache and database best practices.
Task: Bring in RST documentation for Glance (JayPipes has drafted it) and incorporate into the nova.openstack.org site.
Task: Create test page in wiki for second language. Dependency: second-language system for testing.
Task: Contact Japanese authors to see if they would like to author pages in Japanese in the OpenStack wiki. Dependency: Contact info through Bret Piatt.
Test/Demo Plan
None.
Unresolved Issues
Selection of docs.openstack.org engine is unresolved but part of the plan.
