openstack team mailing list archive

[Anne Gentle <anne@xxxxxxxxxxxxx>]

Hi all -
Wanted to send a note out to let people know I'm listening to the various
difficulties finding accurate docs, and also provide my sense of the scope
of the docs for OpenStack.

I want to have a session at the Design Summit about the blossoming docs
sites but also discuss how to prune and de-dupe docs. Here are all the
"doc" properties - not that I own them all, but that they are locations
where people get info that can go out-of-date. I want to prioritize and
focus docs for the Folsom release and welcome your input. This info is
copied to this Etherpad: http://etherpad.openstack.org/folsomdocsplanning,
feel free to edit and add as you see fit.

__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.

Yes, this is a long list. Yes, this is the Internet. Yes, I have ideas for
how to manage all this content, and I'd welcome yours as well.

Thanks for reading this far! Join us at the Summit to discuss in person.
Anne