Open Stack

On Wed, Jul 16, 2014 at 2:55 PM, Ryan Moats <rmoats at us.ibm.com> wrote:

> > From: Gauvain Pocentek <gauvain.pocentek at objectif-libre.com>
> > To: openstack-docs <openstack-docs at lists.openstack.org>
> > Date: 07/16/2014 02:14 PM
> > Subject: [Openstack-docs] Heat templates guide
>
> >
> > 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.
> >
> > - 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've been starting to think that there ought to be various infrastructure
> (or an "under the covers")
> guides, because I've been finding places where, while the existing
> documentation is essentially correct,
> they are incomplete in terms of the details of what exactly is happening.
>
> Adding such details would risk cluttering up the existing document (as
> you've noted) and such
> a set of guides could both provide deeper insight into how particular
> components work and provide
> a natural landing space for documentation such as this.
>
>
Ryan, who's the audience for this type of under the covers doc? Are they
likely to read the code anyway to get the real story? It's difficult to
keep up with the under the covers story -- especially when we don't have
full coverage on the covers. :)

Anne


> Ryan Moats (regXboi)
>
>
> _______________________________________________
> 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/fb550329/attachment.html>