Re: [openstack-dev] [Heat][docs] Need more sample HOT templates for users
On 22/02/14 06:42, Mike Spreitzer wrote: Zane Bitter zbit...@redhat.com wrote on 02/21/2014 12:23:05 PM: Yeah, we are overloading the term 'developer' here, since that section contains both information that is only useful to developers working on Heat itself, and information useful to users developing templates. At the highest levels of the OpenStack documentation, a distinction is made between cloud users, cloud admins, and developers. Nobody coming at this from the outside would look under developer documentation for what a cloud user --- even one writing a Heat template --- needs to know: cloud users are obviously application developers and deployers and operators. I'm not sure if this is forced because of an OpenStack-wide assumption that there is only API documentation and developer documentation? We ought to split these up and make the difference clear if we can. Forget the if. If we don't want to have to mentor every new user, we need decent documentation. https://bugs.launchpad.net/openstack-manuals/+bug/1281691 I think the heat template guide will always use sphinx since it autogenerates the resource reference section by introspecting the heat codebase. Having it as a subdirectory of the developer guide was always meant to be a temporary solution, I see a couple of options: 1. allow the heat repo to generate 2 separate sphinx documentation sets, one developer docs and one template guide 2. move the template guide to openstack-manuals (or some other manual repo) Doing 2 will mean that repo would need to depend on heat, and ideally we could still have a docs job to see what documentation is generated for any heat gerrit review ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [Heat][docs] Need more sample HOT templates for users
On Sun, Feb 23, 2014 at 1:23 PM, Steve Baker sba...@redhat.com wrote: On 22/02/14 06:42, Mike Spreitzer wrote: Zane Bitter zbit...@redhat.com zbit...@redhat.com wrote on 02/21/2014 12:23:05 PM: Yeah, we are overloading the term 'developer' here, since that section contains both information that is only useful to developers working on Heat itself, and information useful to users developing templates. At the highest levels of the OpenStack documentation, a distinction is made between cloud users, cloud admins, and developers. Nobody coming at this from the outside would look under developer documentation for what a cloud user --- even one writing a Heat template --- needs to know: cloud users are obviously application developers and deployers and operators. I'm not sure if this is forced because of an OpenStack-wide assumption that there is only API documentation and developer documentation? We ought to split these up and make the difference clear if we can. Forget the if. If we don't want to have to mentor every new user, we need decent documentation. https://bugs.launchpad.net/openstack-manuals/+bug/1281691 I think the heat template guide will always use sphinx since it autogenerates the resource reference section by introspecting the heat codebase. Having it as a subdirectory of the developer guide was always meant to be a temporary solution, I see a couple of options: 1. allow the heat repo to generate 2 separate sphinx documentation sets, one developer docs and one template guide 2. move the template guide to openstack-manuals (or some other manual repo) Doing 2 will mean that repo would need to depend on heat, and ideally we could still have a docs job to see what documentation is generated for any heat gerrit review Hi Steve, I hesitate to embrace option 1 because the Sphinx output would still live rather separately so I don't know how to provide a better experience to template developers that way. Now that we have a reliable git.openstack.org we often embed source from other project's repositories in openstack-manuals and the api-site repositories. Also realize the entire Configuration Reference is programmatically pulled from five OpenStack repositories already. It would be great to add a chapter about template authoring to an existing guide. The template developers, are they cloud admins or end users more likely? Or maybe Mike, Quiming, or Zane has another idea -- do you think it has to be a separate guide completely? Another idea is that we're putting together a new API and SDK landing page in the coming month, would this user be most likely to visit that? Do you have a resource in mind to put this together? Anne ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [Heat][docs] Need more sample HOT templates for users
On 24/02/14 08:44, Anne Gentle wrote: On Sun, Feb 23, 2014 at 1:23 PM, Steve Baker sba...@redhat.com mailto:sba...@redhat.com wrote: On 22/02/14 06:42, Mike Spreitzer wrote: Zane Bitter zbit...@redhat.com mailto:zbit...@redhat.com wrote on 02/21/2014 12:23:05 PM: Yeah, we are overloading the term 'developer' here, since that section contains both information that is only useful to developers working on Heat itself, and information useful to users developing templates. At the highest levels of the OpenStack documentation, a distinction is made between cloud users, cloud admins, and developers. Nobody coming at this from the outside would look under developer documentation for what a cloud user --- even one writing a Heat template --- needs to know: cloud users are obviously application developers and deployers and operators. I'm not sure if this is forced because of an OpenStack-wide assumption that there is only API documentation and developer documentation? We ought to split these up and make the difference clear if we can. Forget the if. If we don't want to have to mentor every new user, we need decent documentation. https://bugs.launchpad.net/openstack-manuals/+bug/1281691 I think the heat template guide will always use sphinx since it autogenerates the resource reference section by introspecting the heat codebase. Having it as a subdirectory of the developer guide was always meant to be a temporary solution, I see a couple of options: 1. allow the heat repo to generate 2 separate sphinx documentation sets, one developer docs and one template guide 2. move the template guide to openstack-manuals (or some other manual repo) Doing 2 will mean that repo would need to depend on heat, and ideally we could still have a docs job to see what documentation is generated for any heat gerrit review Hi Steve, I hesitate to embrace option 1 because the Sphinx output would still live rather separately so I don't know how to provide a better experience to template developers that way. Now that we have a reliable git.openstack.org http://git.openstack.org we often embed source from other project's repositories in openstack-manuals and the api-site repositories. Also realize the entire Configuration Reference is programmatically pulled from five OpenStack repositories already. If you could point me at some examples of where things are being pulled in from code repos into manuals then I'll take a look. Another repo which would be useful to pull from is heat-templates, which would allow us to store canonical example templates in one place, but include them in manuals. It would be great to add a chapter about template authoring to an existing guide. The template developers, are they cloud admins or end users more likely? Or maybe Mike, Quiming, or Zane has another idea -- do you think it has to be a separate guide completely? I would say end users. If you're doing anything OpenStack with CLIs or Horizon then you should consider automating that by authoring a Heat template. Feel free to suggest an existing manual the template guide could be added too. Currently we have mostly reference docs[1] but I'm hoping to spend a bunch of post-feature-freeze time to start some how-to recipe content (although that is what I said during havana freeze too) Another idea is that we're putting together a new API and SDK landing page in the coming month, would this user be most likely to visit that? I think not, Heat is a layer above API/SDK. Do you have a resource in mind to put this together? I was hoping to spend some time just writing content rather than porting to docbook and reorganizing repos, but it looks like the time has come. [1] http://docs.openstack.org/developer/heat/template_guide/ ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [Heat][docs] Need more sample HOT templates for users
On 02/23/2014 09:14 PM, Steve Baker wrote:
On 24/02/14 08:44, Anne Gentle wrote:
On Sun, Feb 23, 2014 at 1:23 PM, Steve Baker sba...@redhat.com
mailto:sba...@redhat.com wrote:
On 22/02/14 06:42, Mike Spreitzer wrote:
Zane Bitter zbit...@redhat.com mailto:zbit...@redhat.com
wrote on 02/21/2014 12:23:05 PM:
Yeah, we are overloading the term 'developer' here, since that
section
contains both information that is only useful to developers
working on
Heat itself, and information useful to users developing templates.
At the highest levels of the OpenStack documentation, a
distinction is made between cloud users, cloud admins, and
developers. Nobody coming at this from the outside would look
under developer documentation for what a cloud user --- even one
writing a Heat template --- needs to know: cloud users are
obviously application developers and deployers and operators.
I'm not sure if this is forced because of an OpenStack-wide
assumption
that there is only API documentation and developer documentation?
We ought to split these up and make the difference clear if we can.
Forget the if. If we don't want to have to mentor every new
user, we need decent documentation.
https://bugs.launchpad.net/openstack-manuals/+bug/1281691
I think the heat template guide will always use sphinx since it
autogenerates the resource reference section by introspecting the
heat codebase.
Having it as a subdirectory of the developer guide was always
meant to be a temporary solution, I see a couple of options:
1. allow the heat repo to generate 2 separate sphinx documentation
sets, one developer docs and one template guide
2. move the template guide to openstack-manuals (or some other
manual repo)
Doing 2 will mean that repo would need to depend on heat, and
ideally we could still have a docs job to see what documentation
is generated for any heat gerrit review
Hi Steve,
I hesitate to embrace option 1 because the Sphinx output would still
live rather separately so I don't know how to provide a better
experience to template developers that way.
Now that we have a reliable git.openstack.org
http://git.openstack.org we often embed source from other project's
repositories in openstack-manuals and the api-site repositories. Also
realize the entire Configuration Reference is programmatically pulled
from five OpenStack repositories already.
If you could point me at some examples of where things are being pulled
in from code repos into manuals then I'll take a look. Another repo
which would be useful to pull from is heat-templates, which would allow
us to store canonical example templates in one place, but include them
in manuals.
One way is something like doc/common/section_keystone-sample-conf-files.xml:
paraprogramlisting language=inixi:include
parse=text
href=http://git.openstack.org/cgit/openstack/keystone/plain/etc/logging.conf.sample//programlisting/para
It would be great to add a chapter about template authoring to an
existing guide. The template developers, are they cloud admins or end
users more likely? Or maybe Mike, Quiming, or Zane has another idea --
do you think it has to be a separate guide completely?
I would say end users. If you're doing anything OpenStack with CLIs or
Horizon then you should consider automating that by authoring a Heat
template.
Feel free to suggest an existing manual the template guide could be
added too. Currently we have mostly reference docs[1] but I'm hoping to
spend a bunch of post-feature-freeze time to start some how-to recipe
content (although that is what I said during havana freeze too)
We could also add an introduction/overview to one of the guides with a
smallish example and give a link to the template guide from there.
Another idea is that we're putting together a new API and SDK landing
page in the coming month, would this user be most likely to visit that?
I think not, Heat is a layer above API/SDK.
Do you have a resource in mind to put this together?
I was hoping to spend some time just writing content rather than porting
to docbook and reorganizing repos, but it looks like the time has come.
[1] http://docs.openstack.org/developer/heat/template_guide/
Andreas
--
Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi
SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 Nürnberg, Germany
GF: Jeff Hawn,Jennifer Guild,Felix Imendörffer,HRB16746 (AG Nürnberg)
GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126
___
OpenStack-dev mailing list
OpenStack-dev@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [Heat][docs] Need more sample HOT templates for users
On 02/23/2014 01:14 PM, Steve Baker wrote: On 24/02/14 08:44, Anne Gentle wrote: On Sun, Feb 23, 2014 at 1:23 PM, Steve Baker sba...@redhat.com mailto:sba...@redhat.com wrote: On 22/02/14 06:42, Mike Spreitzer wrote: Zane Bitter zbit...@redhat.com mailto:zbit...@redhat.com wrote on 02/21/2014 12:23:05 PM: Yeah, we are overloading the term 'developer' here, since that section contains both information that is only useful to developers working on Heat itself, and information useful to users developing templates. At the highest levels of the OpenStack documentation, a distinction is made between cloud users, cloud admins, and developers. Nobody coming at this from the outside would look under developer documentation for what a cloud user --- even one writing a Heat template --- needs to know: cloud users are obviously application developers and deployers and operators. I'm not sure if this is forced because of an OpenStack-wide assumption that there is only API documentation and developer documentation? We ought to split these up and make the difference clear if we can. Forget the if. If we don't want to have to mentor every new user, we need decent documentation. https://bugs.launchpad.net/openstack-manuals/+bug/1281691 I think the heat template guide will always use sphinx since it autogenerates the resource reference section by introspecting the heat codebase. Having it as a subdirectory of the developer guide was always meant to be a temporary solution, I see a couple of options: 1. allow the heat repo to generate 2 separate sphinx documentation sets, one developer docs and one template guide 2. move the template guide to openstack-manuals (or some other manual repo) Doing 2 will mean that repo would need to depend on heat, and ideally we could still have a docs job to see what documentation is generated for any heat gerrit review Hi Steve, I hesitate to embrace option 1 because the Sphinx output would still live rather separately so I don't know how to provide a better experience to template developers that way. Now that we have a reliable git.openstack.org http://git.openstack.org we often embed source from other project's repositories in openstack-manuals and the api-site repositories. Also realize the entire Configuration Reference is programmatically pulled from five OpenStack repositories already. If you could point me at some examples of where things are being pulled in from code repos into manuals then I'll take a look. Another repo which would be useful to pull from is heat-templates, which would allow us to store canonical example templates in one place, but include them in manuals. It would be great to add a chapter about template authoring to an existing guide. The template developers, are they cloud admins or end users more likely? Or maybe Mike, Quiming, or Zane has another idea -- do you think it has to be a separate guide completely? I would say end users. If you're doing anything OpenStack with CLIs or Horizon then you should consider automating that by authoring a Heat template. Feel free to suggest an existing manual the template guide could be added too. Currently we have mostly reference docs[1] but I'm hoping to spend a bunch of post-feature-freeze time to start some how-to recipe content (although that is what I said during havana freeze too) Another idea is that we're putting together a new API and SDK landing page in the coming month, would this user be most likely to visit that? I think not, Heat is a layer above API/SDK. Do you have a resource in mind to put this together? I was hoping to spend some time just writing content rather than porting to docbook and reorganizing repos, but it looks like the time has come. [1] http://docs.openstack.org/developer/heat/template_guide/ Just to add to this a bit, some reviews have some in which want to document the /contrib directory resources. I don't necessarily think it makes sense for these to be in the main documentation, but rather a cotrib resources document. I'm not sure how to make that happen, but it seems to make the most sense to me. Another option is to mark resources in the documentation that are contrib as such and indicate the cloud provider must enable them for them to be usable. Regards, -steve ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [Heat][docs] Need more sample HOT templates for users
On Sun, Feb 23, 2014 at 2:14 PM, Steve Baker sba...@redhat.com wrote: On 24/02/14 08:44, Anne Gentle wrote: On Sun, Feb 23, 2014 at 1:23 PM, Steve Baker sba...@redhat.com wrote: On 22/02/14 06:42, Mike Spreitzer wrote: Zane Bitter zbit...@redhat.com zbit...@redhat.com wrote on 02/21/2014 12:23:05 PM: Yeah, we are overloading the term 'developer' here, since that section contains both information that is only useful to developers working on Heat itself, and information useful to users developing templates. At the highest levels of the OpenStack documentation, a distinction is made between cloud users, cloud admins, and developers. Nobody coming at this from the outside would look under developer documentation for what a cloud user --- even one writing a Heat template --- needs to know: cloud users are obviously application developers and deployers and operators. I'm not sure if this is forced because of an OpenStack-wide assumption that there is only API documentation and developer documentation? We ought to split these up and make the difference clear if we can. Forget the if. If we don't want to have to mentor every new user, we need decent documentation. https://bugs.launchpad.net/openstack-manuals/+bug/1281691 I think the heat template guide will always use sphinx since it autogenerates the resource reference section by introspecting the heat codebase. Having it as a subdirectory of the developer guide was always meant to be a temporary solution, I see a couple of options: 1. allow the heat repo to generate 2 separate sphinx documentation sets, one developer docs and one template guide 2. move the template guide to openstack-manuals (or some other manual repo) Doing 2 will mean that repo would need to depend on heat, and ideally we could still have a docs job to see what documentation is generated for any heat gerrit review Hi Steve, I hesitate to embrace option 1 because the Sphinx output would still live rather separately so I don't know how to provide a better experience to template developers that way. Now that we have a reliable git.openstack.org we often embed source from other project's repositories in openstack-manuals and the api-site repositories. Also realize the entire Configuration Reference is programmatically pulled from five OpenStack repositories already. If you could point me at some examples of where things are being pulled in from code repos into manuals then I'll take a look. Another repo which would be useful to pull from is heat-templates, which would allow us to store canonical example templates in one place, but include them in manuals. It would be great to pull from heat-templates files directly. In the xml source you'd use something like line 13 of doc/common/section_keystone-sample-conf-files.xml: xi:include parse=text href= http://git.openstack.org/cgit/openstack/keystone/plain/etc/keystone.conf.sample / It would be great to add a chapter about template authoring to an existing guide. The template developers, are they cloud admins or end users more likely? Or maybe Mike, Quiming, or Zane has another idea -- do you think it has to be a separate guide completely? I would say end users. If you're doing anything OpenStack with CLIs or Horizon then you should consider automating that by authoring a Heat template. Feel free to suggest an existing manual the template guide could be added too. Currently we have mostly reference docs[1] but I'm hoping to spend a bunch of post-feature-freeze time to start some how-to recipe content (although that is what I said during havana freeze too) That's great, we have an End User Guide at http://docs.openstack.org/user-guide/content/. Another idea is that we're putting together a new API and SDK landing page in the coming month, would this user be most likely to visit that? I think not, Heat is a layer above API/SDK. Do you have a resource in mind to put this together? I was hoping to spend some time just writing content rather than porting to docbook and reorganizing repos, but it looks like the time has come. I have a few ideas for potential resources to help you, let's chat tomorrow on IRC. I think this placement in the end user guide makes a lot of sense -- Dashboard, CLI users would definitely want to get started with heat templates. Anne [1] http://docs.openstack.org/developer/heat/template_guide/ ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [Heat][docs] Need more sample HOT templates for users
On 14/02/14 03:21, Qiming Teng wrote: On Fri, Feb 14, 2014 at 08:24:09AM +0100, Thomas Spatzier wrote: Thanks, Thomas. The first link actually provides a nice inventory of all Resources and their properties, attributes, etc. I didn't look into this because I was thinking of the word 'developer' differently. This pointer is useful for template developers in the sense that they don't have to check the source code to know a resource type. Yeah, we are overloading the term 'developer' here, since that section contains both information that is only useful to developers working on Heat itself, and information useful to users developing templates. I'm not sure if this is forced because of an OpenStack-wide assumption that there is only API documentation and developer documentation? We ought to split these up and make the difference clear if we can. Maybe more elaborated explanation of resource usage is some work that can be left to book or manual authors. Your original suggestion was a good one - we actually already include the docstrings from resource plugin classes when we generate the template documentation.[1] So we just have to write docstrings for all the resource types... cheers, Zane. [1] https://github.com/openstack/heat/blob/eae9a2ad3f5d3dcbcbb10c88a55fd81f1fe2dd56/doc/source/ext/resources.py#L47 Regards, - Qiming Hi Qiming, not sure if you have already seen it, but there is some documentation available at the following locations. If you already know it, sorry for dup ;-) Entry to Heat documentation: http://docs.openstack.org/developer/heat/ Template Guide with pointers to more details like documentation of all resources: http://docs.openstack.org/developer/heat/template_guide/index.html HOT template guide: http://docs.openstack.org/developer/heat/template_guide/hot_guide.html HOT template spec: http://docs.openstack.org/developer/heat/template_guide/hot_spec.html Regards, Thomas Qiming Teng teng...@linux.vnet.ibm.com wrote on 14/02/2014 06:55:56: From: Qiming Teng teng...@linux.vnet.ibm.com To: openstack-dev@lists.openstack.org Date: 14/02/2014 07:04 Subject: [openstack-dev] [Heat] Need more sample HOT templates for users Hi, I have been recently trying to convince some co-workers and even some customers to try deploy and manipulate their applications using Heat. Here are some feedbacks I got from them, which could be noteworthy for the Heat team, hopefully. - No document can be found on how each Resource is supposed to be used. This is partly solved by the adding resource_schema API but it seems not yet exposed by heatclient thus the CLI. In addition to this, resource schema itself may print only simple help message in ONE sentence, which could be insufficient for users to gain a full understanding. - The current 'heat-templates' project provides quite some samples in the CFN format, but not so many in HOT format. For early users, this means either they will get more accustomed to CFN templates, or they need to write HOT templates from scratch. Another suggestion is also related to Resource usage. Maybe more smaller HOT templates each focusing on teaching one or two resources would be helpful. There could be some complex samples as show cases as well. Some thoughts on documenting the Resources: - The doc can be inlined in the source file, where a developer provides the manual of a resource when it is developed. People won't forget to update it if the implementation is changed. A Resource can provide a 'describe' or 'usage' or 'help' method to be inherited and implemented by all resource types. One problem with this is that code mixed with long help text may be annoying for some developers. Another problem is about internationalization. - Another option is to create a subdirectory in the doc directory, dedicated to resource usage. In addition to the API references, we also provide resource references (think of the AWS CFN online docs). Does this makes senses? Regards, - Qiming - Qiming Teng, PhD. Research Staff Member IBM Research - China e-mail: teng...@cn.ibm.com ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [Heat][docs] Need more sample HOT templates for users
Zane Bitter zbit...@redhat.com wrote on 02/21/2014 12:23:05 PM: Yeah, we are overloading the term 'developer' here, since that section contains both information that is only useful to developers working on Heat itself, and information useful to users developing templates. At the highest levels of the OpenStack documentation, a distinction is made between cloud users, cloud admins, and developers. Nobody coming at this from the outside would look under developer documentation for what a cloud user --- even one writing a Heat template --- needs to know: cloud users are obviously application developers and deployers and operators. I'm not sure if this is forced because of an OpenStack-wide assumption that there is only API documentation and developer documentation? We ought to split these up and make the difference clear if we can. Forget the if. If we don't want to have to mentor every new user, we need decent documentation. https://bugs.launchpad.net/openstack-manuals/+bug/1281691 Regards, Mike___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
