Difference between revisions of "DocImprovementsSpec"
(talk) |
(Do not restrict it to Bexar) |
||
| Line 1: | Line 1: | ||
__NOTOC__ | __NOTOC__ | ||
| + | <!-- ## page was renamed from [[BexarDocSpec]] --> | ||
* '''Launchpad Entry''': https://blueprints.launchpad.net/openstack-devel/+spec/doc-enhancements | * '''Launchpad Entry''': https://blueprints.launchpad.net/openstack-devel/+spec/doc-enhancements | ||
* '''Created''': 2010-11-29 | * '''Created''': 2010-11-29 | ||
| Line 10: | Line 11: | ||
== Release Note == | == Release Note == | ||
| − | OpenStack strives for professional-level documentation created collaboratively with contributors from around the world. With this release of OpenStack, . | + | 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 == | == Rationale == | ||
| Line 17: | Line 18: | ||
== User stories == | == User stories == | ||
| + | |||
| + | To be written. | ||
== Assumptions == | == Assumptions == | ||
| Line 25: | Line 28: | ||
=== Docs site === | === 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). | 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=== | + | === 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. | 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=== | + | === 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. | 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 === | === 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. | 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 === | === 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: | 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: | ||
| Line 46: | Line 54: | ||
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? | 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=== | + | === Glance docs === |
| − | With the Glance implementation still ongoing for Bexar, we need to plan for install and integration docs with the Bexar release. | + | |
| + | 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 === | === 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 == | == Implementation == | ||
Revision as of 15:14, 15 December 2010
- 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, 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
To be written.
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. 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
TBD, see WebContentRequirements for a list of requirements and possible implementation tools.
Test/Demo Plan
None.
Unresolved Issues
None.
