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
