> 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 actually think developer.openstack.org is perfect - it has the “developer” subdomain which is familiar to API/SDK consumers plus it has the “.org” TLD which has the non-commercial connotation. Agree with #2 that that needs of consumers > needs of contributors. When you know, could you share the mechanics of publishing user-facing SDK documentation from its source repo to the appropriate destination on developer.openstack.org? Thanks, Shaunak On Apr 28, 2014, at 2:53 PM, Anne Gentle <[email protected]> wrote: > > > > 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.org > todeveloper.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.org > landing 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 > > athttp://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 > > thinkhttp://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 > > [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 _______________________________________________ OpenStack-dev mailing list [email protected] http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
