Re: [openstack-dev] [Heat][docs] Need more sample HOT templates for users

[Anne Gentle]

On Sun, Feb 23, 2014 at 2: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  wrote:
>
>>   On 22/02/14 06:42, Mike Spreitzer wrote:
>>
>> Zane Bitter   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:

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

[Steven Dake]

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 > wrote:


On 22/02/14 06:42, Mike Spreitzer wrote:

Zane Bitter  
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 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

[Andreas Jaeger]

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 > > wrote:
>>
>> On 22/02/14 06:42, Mike Spreitzer wrote:
>>> Zane Bitter  
>>> 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.

One way is something like doc/common/section_keystone-sample-conf-files.xml:

http://git.openstack.org/cgit/openstack/keystone/plain/etc/logging.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)

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

[Steve Baker]

On 24/02/14 08:44, Anne Gentle wrote:
>
>
>
> On Sun, Feb 23, 2014 at 1:23 PM, Steve Baker  > wrote:
>
> On 22/02/14 06:42, Mike Spreitzer wrote:
>> Zane Bitter  
>> 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 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

[Anne Gentle]

On Sun, Feb 23, 2014 at 1:23 PM, Steve Baker  wrote:

>  On 22/02/14 06:42, Mike Spreitzer wrote:
>
> Zane Bitter   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

[Steve Baker]

On 22/02/14 06:42, Mike Spreitzer wrote:
> Zane Bitter  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

[Mike Spreitzer]

Zane Bitter  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

Re: [openstack-dev] [Heat][docs] Need more sample HOT templates for users

[Zane Bitter]

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  wrote on 14/02/2014 06:55:56:


From: Qiming Teng 
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