Open Stack

Shaunak, these are some good questions. Input from the docs team would
be useful for some of these as well.

On Wed, Apr 16, 2014 at 10:06 PM, Shaunak Kashyap
<shaunak.kashyap at rackspace.com> wrote:
> 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?

For this I'll go by example first. If you look at something like the
OpenStack Client docs
(http://git.openstack.org/cgit/openstack/python-openstackclient/tree/doc)
you'll see they are currently published to
http://docs.openstack.org/developer/python-openstackclient/. The same
is true of other projects as well.

I'm not sure this is the ideal place but it is where things are
published to now. There has been talk of producing a
developers.openstack.org. The initial proposed content for that
currently resides at api.openstack.org. If a more detailed portal
comes together that would be a good place for this.

>
> 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/).

If you take a look at the general SDK development page
(https://wiki.openstack.org/wiki/SDK-Development) there is a
description of the target audience. This target audience is a little
different from most of the other documentation so we should take that
into account.

We shouldn't expect a user of the SDK to understand the internals of
OpenStack or even the names such as swift, nova, etc. An application
developer will likely know little about OpenStack other than it's a
cloud platform. The SDK should introduce them to OpenStack with the
limited amount of knowledge a dev would need to know.

>From here I like your idea of a section for each service (e.g.,
identity). This make sense.

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

Great. We want to help application developers get up to speed quickly.
They're concerned with their app. I like the idea of common use cases
near the front.