Open Stack

On Wed, Jul 16, 2014 at 2:13 PM, Gauvain Pocentek <
gauvain.pocentek at objectif-libre.com> wrote:

> Hi all,
>
> We discussed how to add a HOT template guide ([bp]) off list and we'd like
> to have some feedback before getting really started.
>
> So what we plan to do is:
>
> - Write the guide in RST and generate a docbook chapter (the tool to do so
> is almost ready) that will be included in the user guide. We really think
> this is the way to go, because we want to make things easier for developers
> to contribute. So unless there are strong feelings against this, we'll
> probably get started soon.
>
>
I'm okay with this, but will say in my experience rst to docbook is fiddly
and you only want to do it once, it's not automatable. (I know you're not
talking about repeated imports, just one time.)

One thing I noted is that there is already an RST guide, but I've gotten
feedback that it's too simple of an example and we'll want to add a more
real-world example. So I'd say start with the RST files that exists at
http://git.openstack.org/cgit/openstack/heat/tree/doc/source/template_guide
and go from there.


> - We (I?)'d like to include the HOT reference ([ref]) in the manuals, but
> we're not sure where we should include it. Including it in the user guide
> would probably clutter this guide, the CLI and config references don't look
> like good candidates either, and another guide just for this is probably
> overkill. A last solution is to keep the (unversioned) reference in the
> developer/ namespace.
> What do you guys think about this?
>
>
I think that the HOT Reference can be a separate guide like the CLI Ref and
Config Ref. It's not a lot of overhead since it's automatically generated.

Anne


> Thanks,
> Gauvain
>
> [bp]: https://blueprints.launchpad.net/openstack-manuals/+spec/
> heat-templates)
> [ref]: http://docs.openstack.org/developer/heat/template_guide/
>
>
> _______________________________________________
> Openstack-docs mailing list
> Openstack-docs at lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140717/9664bf77/attachment.html>