<div dir="ltr">Great questions, Shaunak. Yep I've been thinking about this for a while but not sure I have complete conclusions. More below.<br><div class="gmail_extra"><br><br><div class="gmail_quote">On Wed, Apr 16, 2014 at 9:06 PM, Shaunak Kashyap <span dir="ltr"><<a href="mailto:shaunak.kashyap@rackspace.com" target="_blank">shaunak.kashyap@rackspace.com</a>></span> wrote:<br>
<blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">Hi folks,<br>
<br>
As part of working on <a href="https://blueprints.launchpad.net/openstack-sdk-php/+spec/sphinx-docs" target="_blank">https://blueprints.launchpad.net/openstack-sdk-php/+spec/sphinx-docs</a>, I’ve been looking at <a href="http://git.openstack.org/cgit/stackforge/openstack-sdk-php/tree/doc" target="_blank">http://git.openstack.org/cgit/stackforge/openstack-sdk-php/tree/doc</a>.<br>
<br>
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:<br>
<br>
1. Where and how should the user guide (i.e. Sphinx-generated docs) be published?<br></blockquote><div><br></div><div>Just to give some context and background, we have a User Guide with a Python SDK chapter: <a href="http://docs.openstack.org/user-guide/content/">http://docs.openstack.org/user-guide/content/</a></div>
<div><br></div><div>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. </div>
<div><br></div><div>What's that? For REST APIs, developers typically expect:</div><div><a href="http://developer.example.com">developer.example.com</a> - for docs, examples, code, links to download dev kits.</div><div>
<a href="http://api.example.com">api.example.com</a> - for the actual api endpoints. </div><div><br></div><div>What's tough for us is that there are thousands of OpenStack endpoints by now. A few years back we created <a href="http://api.openstack.org">api.openstack.org</a>, 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 <a href="http://developer.openstack.org">developer.openstack.org</a>. </div>
<div><br></div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">
<br>
I know there’s <a href="http://docs.openstack.org/" target="_blank">http://docs.openstack.org/</a>. 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?<br>
</blockquote><div><br></div><div><br class="">What's tough about correcting our doc domains going forward is that we have <a href="http://docs.openstack.org/developer">docs.openstack.org/developer</a> 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 <a href="http://developer.openstack.org">developer.openstack.org</a> to be that landing point for all language devs looking to consume OpenStack cloud resources from any provider.<br>
</div><div><br></div><div>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.</div>
<div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">
<br>
2. How should the user guide(s) be organized?<br>
<br>
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. <a href="http://docs.openstack.org/api/openstack-object-storage/1.0/content/" target="_blank">http://docs.openstack.org/api/openstack-object-storage/1.0/content/</a>).<br>
</blockquote><div><br></div><div>Agreed. Please use the service name not our crazy code names. :)</div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">
<br>
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 <a href="http://git.openstack.org/cgit/stackforge/openstack-sdk-php/tree/doc/oo-tutorial.md" target="_blank">http://git.openstack.org/cgit/stackforge/openstack-sdk-php/tree/doc/oo-tutorial.md</a> 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.<br>
</blockquote><div><br></div><div>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.</div>
<div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">
<br>
Cc’ing Anne Gentle since she probably has informed opinions on both these questions.<br></blockquote><div><br></div><div><br></div><div>Sure do - I think some first steps should be:</div><div> * Get <a href="http://developer.openstack.org">developer.openstack.org</a> domain name (pre-Summit)</div>
<div> * Serve up the content from the <a href="http://api.openstack.org">api.openstack.org</a> landing page from <a href="http://developer.openstack.org">developer.openstack.org</a> (pre-Summit)</div><div> * Redirect content from <a href="http://api.openstack.org">api.openstack.org</a> to <a href="http://developer.openstack.org">developer.openstack.org</a> (just one page right now) (pre-Summit)</div>
<div> * 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 <a href="http://junodesignsummit.sched.org/event/ae9afc77278abb98f0fc35a540a1bb0b#.U1VkNeZdUqY">http://junodesignsummit.sched.org/event/ae9afc77278abb98f0fc35a540a1bb0b#.U1VkNeZdUqY</a></div>
<div> * Goals to accomplish at this summit session:</div><div> - agree to the doc outlines </div><div> - agree to the doc landing pages</div><div> - decide on who reviews and approves content</div><div><br></div><div>
Thoughts? Anything I'm missing?</div><div>Anne</div><div><br></div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">
<br>
Thanks,<br>
<br>
Shaunak<br>
<br>
<br>
<br>
_______________________________________________<br>
OpenStack-dev mailing list<br>
<a href="mailto:OpenStack-dev@lists.openstack.org">OpenStack-dev@lists.openstack.org</a><br>
<a href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev" target="_blank">http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev</a><br>
</blockquote></div><br></div></div>