DocImprovementsSpec
- Launchpad Entry: https://blueprints.launchpad.net/openstack-devel/+spec/doc-enhancements
- Created: 2010-11-29
- Contributors: AnneGentle
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, .
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
Assumptions
None.
Design
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.
Localization
With the increasing interest in OpenStack in other countries we need a system that enables contributors to translate existing English docs OR create documentation in their native language.
Implementation
TBD, see WebContentRequirements for a list of requirements and possible implementation tools.
Test/Demo Plan
None.
Unresolved Issues
None.
