说实话，openstack的文档有点乱，分散在几个地方。
这次会议上，有几个议题就是谈文档的，这里给出了一个官方文档列表：
http://etherpad.openstack.org/folsomdocsplanning
Session: http://summit.openstack.org/sessions/view/151
Blueprint:
Presenter: Anne Gentle, OpenStack Content Stacker at Rackspace, anne@openstack.org
zSession Goals:
Discuss criteria for priorities – audience? Reach based on web views? Others?
Describe the top three priorities for the timeframe of April 2012 to October 2012. Vote on these listed priorities:
1. Configuration information and reference architectures/scenarios for deployments, point out what
2. CLI documentation
3. Add Quantum to Compute guides
4. Move narrative docs from rst to main manuals
5. Redesign landing page based on personas
6. Genericize install docs for distros
Make it easy to report bug
Make it easy to find
Real deployment – config options
examples of different configurations!
keeping in mind the hardware arch and switch config required by those OpenStack configs
see “best practices” below
point out things that will change “at scale”
identify “deployers” as a key audience for the docs, differentiated from “admin”
Examples of how to interact with the API (go beyond JSON blobs)
Explain policy.json and how the defaults control which parts of the API are admin and which are not
Add Quantum to the compute guide
python clients (CLI)
best practices at virtualization layer and choices in images
“if you don’t know what you’re doing, do this”
make the installation docs more generic to include distros other than Ubuntu
need to identify key distros
persona-based landing page redesign
–how to find a source of truth
move narrative docs from rst to main manuals
Understand the breadth and depth of the sites used for documentation.
Should documentation keep up with milestone release points?
Description of all the sites used for various documentation processes:
Site Visitors per month (March-April 2012)
www 113,103
docs 95,907
wiki 58,367
swift 14,313
nova 13,885
api 2,666
__Admin guides__
Where: http://github.com/openstack/openstack-manuals
What:
– docs.openstack.org
– Compute Admin manual
– Object Storage Admin manual
– Supporting projects such as identity and image management are shared chapters inserted into each.
– Network connectivity (Quantum) Admin manual
Who:
Day-to-day administrators of OpenStack clouds (public and private)
How: Updated through the git/Gerrit review process.
__Install guides__
Where: http://github.com/openstack/openstack-manuals
What: docs.openstack.org Compute Install/Deploy guide with identity, image management, dashboard as chapters.
How: Updated through the git/Gerrit review process.
Where: http://launchpad.net/openstackbook
What: docs.openstack.org Ubuntu release-based OpenStack Starter Guide for Natty (Cactus), Oneiric (Diablo), Precise (Essex) soon to be completed
How: Updated through bzr/Launchpad merge processes.
Where: http://www.hastexo.com/resources/docs/installing-openstack-essex-4-ubuntu-1204-precise-pangolin
What: 12.04 Quick Start from Hastexo. It’s a great doc, but I think it could receive even more attention and updates if it were in the OpenStack docs umbrella, so I’m talking to the authors about submitting it.
Who:
Deployers of OpenStack clouds (public and private), proof-of-concept creators
__API info__
Where:
http://github.com/openstack/openstack-manuals
http://github.com/openstack/object-api
http://github.com/openstack/compute-api
http://github.com/openstack/netconn-api
http://github.com/openstack/identity-api
http://github.com/openstack/image-api
What:
openstack-manuals contains:
– docs.openstack.org
– API Quick Start
– Compute API Programmer’s Guide
– api.openstack.org
– OpenStack Compute extensions
Separate repos contain:
(pointed to from docs.openstack.org/api)
– OpenStack Compute API Dev Guide
– OpenStack Object Storage API Dev Guide
– OpenStack Image API Dev Guide
– OpenStack Identity API Dev Guide
– OpenStack Quantum API Dev Guide
Note: In making this listing I realized that Melange has an API spec at https://github.com/openstack/melange/blob/master/doc/source/apidoc.rst. Their latest commit says they make it so it builds to rtfd.org but I can’t find it on that site. Note sent to Dan and Troy.
Who: API programmers, Python developers
How: Updated through the git/Gerrit review process.
__Wiki__
Where: http://wiki.openstack.org
What: Release notes, project status and process information, very little how-to
Who: Contributors to the OpenStack projects
__Developer info__
Where: http://github.com/openstack/nova/
http://github.com/openstack/swift/
http://github.com/openstack/keystone/
http://github.com/openstack/glance/
http://github.com/openstack/horizon/
http://github.com/openstack/openstack-ci/
What:
http://nova.openstack.org
http://swift.openstack.org
http://keystone.openstack.org
http://glance.openstack.org
http://horizon.openstack.org
http://ci.openstack.org
__Main website__
Where: Silverstripe CMS with a few people with logins
What: openstack.org and all pages in it
Who: People who want to learn about OpenStack, community members, company members
__Related websites__
Where: http://github.com/openstack-dev/devstack
What: http://devstack.org
Where: not sure, probably Silverstripe CMS with a few people with logins
What: http://trystack.org
Who: People who want to learn about OpenStack, community members, company members
__Third party blogs and websites__
Where: The Internet
What: How-to and conceptual information about OpenStack
Who: Bloggers
How: I tend to link to good how-to information from bloggers at http://wiki.openstack.org/BloggersTips. Better curation methods would be great. I also contact bloggers directly and work with them to bring in CC licensed content to openstack-manuals.
__Planet Feeds__
Where: http://planet.openstack.org
What: Misc. blogs
Who: Bloggers
How: http://wiki.openstack.org/AddingYourBlog
__OpenStack directory / Satellite__
Where: TBD (asked for satellite.openstack.org)
What: List of projects related to OpenStack
Who: developers, deployers
How: TBD