Open Stack

Thanks for your inputs, Matt and Anne. I’m punting on the first question (re: publishing) for now. It sounds like this is a larger discussion and we can make progress on the PHP SDK user-facing documentation without answering it right away. I’ll bring it up again if we don’t have an answer by the time we have something worth publishing.

Based on your inputs I’ve created this spec: https://wiki.openstack.org/wiki/OpenStack-SDK-PHP/UserFacingDocumentation. Feel free to comment on it. I intend to start implementing it within a week or so.

Thank you,

Shaunak

On Apr 21, 2014, at 11:40 AM, Anne Gentle <anne.gentle at RACKSPACE.COM> wrote:

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