Open Stack

Hi folks,

As part of working on https://blueprints.launchpad.net/openstack-sdk-php/+spec/sphinx-docs, I’ve been looking at http://git.openstack.org/cgit/stackforge/openstack-sdk-php/tree/doc.

Before I start making any changes toward that BP, however, I wanted to put forth a couple of overarching questions and proposals to the group:

1. Where and how should the user guide (i.e. Sphinx-generated docs) be published?

I know there’s http://docs.openstack.org/. It seems like the logical place for these to be linked off of but where would that link go and what is the process of publishing our Sphinx-generated docs to that place?

2. How should the user guide(s) be organized?

If I were a developer, I’m probably looking to use a particular OpenStack service (as opposed to learning about the PHP SDK without a particular orientation). So I propose organizing the PHP SDK user guide accordingly: as a set of user guides, each showing how to use the OpenStack PHP SDK for a particular service. Of course, Identity is common to all so it’s documentation would somehow be included in each user guide. This is similar to how OpenStack organizes its REST API user guides - one per service (e.g. http://docs.openstack.org/api/openstack-object-storage/1.0/content/).

Further, within each user guide, I propose ordering the content according to popularity of use cases for that service (with some other constraints such as introducing concepts first, grouping similar concepts, etc.). This ensures that the reader can get what they want, from their perspective. Particularly, beginners would get what they came for without having to read too far into the documentation. As an example, I think http://git.openstack.org/cgit/stackforge/openstack-sdk-php/tree/doc/oo-tutorial.md does a fine job of walking the user through common Object Store use cases. I would just extend it to gradually introduce the user to more advanced use cases as well, thereby completing the user guide for Object Store.

Cc’ing Anne Gentle since she probably has informed opinions on both these questions.

Thanks,

Shaunak