Open Stack

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: tengqim at cn.ibm.com