Open Stack

Great questions, Shaunak. Yep I've been thinking about this for a while but
not sure I have complete conclusions. More below.


On Wed, Apr 16, 2014 at 9: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?
>

Just to give some context and background, we have a User Guide with a
Python SDK chapter: http://docs.openstack.org/user-guide/content/

A PHP SDK chapter might be a good addition, if you look at what we have and
a pattern that exists, but I'd REALLY like us to break out of the book
model and try to create a developer portal with a more page-centered model.

What's that? For REST APIs, developers typically expect:
developer.example.com - for docs, examples, code, links to download dev
kits.
api.example.com - for the actual api endpoints.

What's tough for us is that there are thousands of OpenStack endpoints by
now. A few years back we created api.openstack.org, but didn't realize
there's an existing pattern of what devs look for from REST APIs. My bad, I
hope we can correct that by creating developer.openstack.org.



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


What's tough about correcting our doc domains going forward is that we have
docs.openstack.org/developer for all the contributor dev docs. I do want to
continue to separate out the audiences: the contributors are Python devs,
the app devs are all languages. I'd like developer.openstack.org to be that
landing point for all language devs looking to consume OpenStack cloud
resources from any provider.

Another difficulty is, how do we govern and review this content? Or do we?
Does it fall under the Documentation Program mission? Right now our mission
states we only cover "core" projects (the definition being just a handful
of projects) and users as top priority. So I see a developer portal as a
user priority. I'm not trying to do a land-grab as a PTL here, but trying
to serve users as best we can, and this is definitely an underserved
audience. The TC has a stance of "code or it doesn't count" so stackforge
seems like a good starting place. Then core teams can form with
deliverables, one of which can be docs. I think we're on the right track
here, just making sure I state the potential decision point on how to
govern SDKs and their docs and form communities around them.


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

Agreed. Please use the service name not our crazy code names. :)


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

I think this approach also makes sense. Very user-centric. The only
additional overarching organization you might consider is a few classic
architectures: ecommerce, high performance computing, media serving,
failover design, that sort of cross-service document might help this
audience get going.


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


Sure do - I think some first steps should be:
 * Get developer.openstack.org domain name (pre-Summit)
 * Serve up the content from the api.openstack.org landing page from
developer.openstack.org (pre-Summit)
 * Redirect content from api.openstack.org to developer.openstack.org (just
one page right now) (pre-Summit)
 * Talk at the design summit about doc creation and governance for SDKs in
the cross-project session, OpenStack Clients and SDKs and project
libraries, a double session starting with
http://junodesignsummit.sched.org/event/ae9afc77278abb98f0fc35a540a1bb0b#.U1VkNeZdUqY
 * Goals to accomplish at this summit session:
   - agree to the doc outlines
   - agree to the doc landing pages
   - decide on who reviews and approves content

Thoughts? Anything I'm missing?
Anne



>
> Thanks,
>
> Shaunak
>
>
>
> _______________________________________________
> OpenStack-dev mailing list
> OpenStack-dev at lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20140421/83a7e9aa/attachment.html>