<html>
<head>
<meta content="text/html; charset=ISO-8859-1"
http-equiv="Content-Type">
</head>
<body bgcolor="#FFFFFF" text="#000000">
<div class="moz-cite-prefix">On 24/02/14 08:44, Anne Gentle wrote:<br>
</div>
<blockquote
cite="mid:CAD0KtVFx+8Q4eOT10fA5JF4C1cgFof7EWN4=AHtQGqWQsJxXPg@mail.gmail.com"
type="cite">
<div dir="ltr"><br>
<div class="gmail_extra"><br>
<br>
<div class="gmail_quote">On Sun, Feb 23, 2014 at 1:23 PM,
Steve Baker <span dir="ltr"><<a moz-do-not-send="true"
href="mailto:sbaker@redhat.com" target="_blank">sbaker@redhat.com</a>></span>
wrote:<br>
<blockquote class="gmail_quote" style="margin:0 0 0
.8ex;border-left:1px #ccc solid;padding-left:1ex">
<div bgcolor="#FFFFFF" text="#000000">
<div>
<div class="h5">
<div>On 22/02/14 06:42, Mike Spreitzer wrote:<br>
</div>
<blockquote type="cite"><tt><font>Zane Bitter <a
moz-do-not-send="true"
href="mailto:zbitter@redhat.com"
target="_blank"><zbitter@redhat.com></a>
wrote on 02/21/2014 12:23:05 PM:<br>
<br>
> Yeah, we are overloading the term
'developer' here, since that section <br>
> contains both information that is only
useful to developers working on <br>
> Heat itself, and information useful to
users developing templates.</font></tt> <br>
<br>
<tt><font>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.</font></tt> <br>
<tt><font><br>
> I'm not sure if this is forced because of
an OpenStack-wide assumption <br>
> that there is only API documentation and
developer documentation?<br>
> <br>
> We ought to split these up and make the
difference clear if we can.<br>
</font></tt> <br>
<tt><font>Forget the "if". If we don't want to
have to mentor every new user, we need decent
documentation.</font></tt> <br>
<br>
<a moz-do-not-send="true"
href="https://bugs.launchpad.net/openstack-manuals/+bug/1281691"
target="_blank"><tt><font>https://bugs.launchpad.net/openstack-manuals/+bug/1281691</font></tt></a>
<br>
</blockquote>
</div>
</div>
<p>I think the heat template guide will always use
sphinx since it autogenerates the resource reference
section by introspecting the heat codebase.</p>
<p>Having it as a subdirectory of the developer guide
was always meant to be a temporary solution, I see a
couple of options:</p>
<p>1. allow the heat repo to generate 2 separate sphinx
documentation sets, one developer docs and one
template guide<br>
2. move the template guide to openstack-manuals (or
some other manual repo)</p>
<p>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</p>
</div>
<br>
</blockquote>
<div><br>
</div>
<div>Hi Steve, </div>
<div>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.</div>
<div><br>
</div>
<div>Now that we have a reliable <a moz-do-not-send="true"
href="http://git.openstack.org">git.openstack.org</a> 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.</div>
<div><br>
</div>
</div>
</div>
</div>
</blockquote>
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.<br>
<br>
<blockquote
cite="mid:CAD0KtVFx+8Q4eOT10fA5JF4C1cgFof7EWN4=AHtQGqWQsJxXPg@mail.gmail.com"
type="cite">
<div dir="ltr">
<div class="gmail_extra">
<div class="gmail_quote">
<div>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?</div>
<div><br>
</div>
</div>
</div>
</div>
</blockquote>
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.<br>
<br>
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)<br>
<br>
<blockquote
cite="mid:CAD0KtVFx+8Q4eOT10fA5JF4C1cgFof7EWN4=AHtQGqWQsJxXPg@mail.gmail.com"
type="cite">
<div dir="ltr">
<div class="gmail_extra">
<div class="gmail_quote">
<div>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?</div>
<div><br>
</div>
</div>
</div>
</div>
</blockquote>
I think not, Heat is a layer above API/SDK.<br>
<blockquote
cite="mid:CAD0KtVFx+8Q4eOT10fA5JF4C1cgFof7EWN4=AHtQGqWQsJxXPg@mail.gmail.com"
type="cite">
<div dir="ltr">
<div class="gmail_extra">
<div class="gmail_quote">
<div>Do you have a resource in mind to put this together? </div>
</div>
</div>
</div>
</blockquote>
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.<br>
<br>
[1] <a class="moz-txt-link-freetext" href="http://docs.openstack.org/developer/heat/template_guide/">http://docs.openstack.org/developer/heat/template_guide/</a><br>
</body>
</html>