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 <[email protected]> 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. _______________________________________________ OpenStack-dev mailing list [email protected] http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
