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