Re: [openstack-dev] [openstack-sdk-php] Questions about user-facing documentation
On Sun, Apr 27, 2014 at 7:57 PM, Shaunak Kashyap shaunak.kash...@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.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
Re: [openstack-dev] [openstack-sdk-php] Questions about user-facing documentation
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 a...@openstack.org wrote: On Sun, Apr 27, 2014 at 7:57 PM, Shaunak Kashyap shaunak.kash...@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.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 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 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
Re: [openstack-dev] [openstack-sdk-php] Questions about user-facing documentation
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
Re: [openstack-dev] [openstack-sdk-php] Questions about user-facing documentation
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.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
Re: [openstack-dev] [openstack-sdk-php] Questions about user-facing documentation
Shaunak, these are some good questions. Input from the docs team would be useful for some of these as well. On Wed, Apr 16, 2014 at 10: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? For this I'll go by example first. If you look at something like the OpenStack Client docs (http://git.openstack.org/cgit/openstack/python-openstackclient/tree/doc) you'll see they are currently published to http://docs.openstack.org/developer/python-openstackclient/. The same is true of other projects as well. I'm not sure this is the ideal place but it is where things are published to now. There has been talk of producing a developers.openstack.org. The initial proposed content for that currently resides at api.openstack.org. If a more detailed portal comes together that would be a good place for this. 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? 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/). If you take a look at the general SDK development page (https://wiki.openstack.org/wiki/SDK-Development) there is a description of the target audience. This target audience is a little different from most of the other documentation so we should take that into account. We shouldn't expect a user of the SDK to understand the internals of OpenStack or even the names such as swift, nova, etc. An application developer will likely know little about OpenStack other than it's a cloud platform. The SDK should introduce them to OpenStack with the limited amount of knowledge a dev would need to know. From here I like your idea of a section for each service (e.g., identity). This make sense. 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. Great. We want to help application developers get up to speed quickly. They're concerned with their app. I like the idea of common use cases near the front. ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
[openstack-dev] [openstack-sdk-php] Questions about user-facing documentation
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? 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? 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/). 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. Cc’ing Anne Gentle since she probably has informed opinions on both these questions. Thanks, Shaunak ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
