On Sun, Apr 27, 2014 at 7:57 PM, Shaunak Kashyap < [email protected]> wrote:
> 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. > > Great details, Shaunak! I say go for it. I'm working with the Foundation and infra team to get developer.openstack.org registered and then we'll redirect api.openstack.orgto developer.openstack.org. Look for that change this week. We had a good discussion on IRC about some of the possible difficulties with this domain: 1) is the developer.example.com standard commercial-based and not open-source? and 2) will developers who want to contribute to OpenStack be confused by this additional subdomain? For 1), I don't believe there's a good open source equivalent we'd want to emulate. For 2), I think the numbers of app developers will far outnumber the contributor developers and their needs outweigh the contributor developers for their own landing page. I do want to mitigate these concerns by redesigning the docs.openstack.orglanding page to ensure that app devs know there's a site just for them (not just for docs but for downloading tools like SDKs.) I would love to get input on how to best grow the developer site and engage that community further. Thanks, Anne > Thank you, > > Shaunak > > On Apr 21, 2014, at 11:40 AM, Anne Gentle <[email protected]> > 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 < > [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? > > > > 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 > > [email protected] > > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev > > > > _______________________________________________ > > OpenStack-dev mailing list > > [email protected] > > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev > > > _______________________________________________ > OpenStack-dev mailing list > [email protected] > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev >
_______________________________________________ OpenStack-dev mailing list [email protected] http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
