[openstack-dev] [openstack-sdk-php] Questions about user-facing documentation

Anne Gentle anne at openstack.org
Mon Apr 28 21:53:19 UTC 2014


On Sun, Apr 27, 2014 at 7:57 PM, Shaunak Kashyap <
shaunak.kashyap at rackspace.com> 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 <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.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
> >
> > _______________________________________________
> > 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
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20140428/0e22eb27/attachment.html>


More information about the OpenStack-dev mailing list