I’m supposed to be strategic about documentation and well, I have to say I feel a bit behind in creating specs for documentation for the upcoming OpenStack releases. Much spec planning went on at the Summit, but I was so focused on the Doc Sprint that I didn’t set any concrete doc plans for Bexar and Cactus releases. I’d like to amend that and get input from everyone in the community and beyond. Here are some ideas that go into a single blueprint for documentation. I’d love to get feedback on these plans and specifications, which we can edit on the wiki.
1. 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).
2. 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.
3. Versioning documentation – We are taking small steps towards a frozen release page/site. For example, you should be able to 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.
4. 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.
5. 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:
- 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?)
- Build your own CDN to serve video content
- Academic calculations where you spin up 10 machines for a Mathematica project only for a day or so
- 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?
6. Glance docs – With the Glance implementation still ongoing for Bexar, we need to plan for install and integration docs with the Bexar release.
Let me know your priorities for upcoming releases and we’ll update the specs for the encapsulating blueprint for docs work. The Docs site is the biggest item needing design and architecture, so I’d welcome input and ideas with a heavy weighting towards “Docs site!”