<div dir="ltr"><br><div class="gmail_extra"><br><br><div class="gmail_quote">On Sun, Feb 23, 2014 at 2:14 PM, Steve Baker <span dir="ltr"><<a href="mailto:sbaker@redhat.com" target="_blank">sbaker@redhat.com</a>></span> wrote:<br>
<blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">
<div bgcolor="#FFFFFF" text="#000000"><div class="">
<div>On 24/02/14 08:44, Anne Gentle wrote:<br>
</div>
<blockquote 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 href="mailto:sbaker@redhat.com" target="_blank">sbaker@redhat.com</a>></span>
wrote:<br>
<blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">
<div bgcolor="#FFFFFF" text="#000000">
<div>
<div>
<div>On 22/02/14 06:42, Mike Spreitzer wrote:<br>
</div>
<blockquote type="cite"><tt><font>Zane Bitter <a 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 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 href="http://git.openstack.org" target="_blank">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></div>
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.</div></blockquote><div><br></div><div>It would be great to pull from heat-templates files directly. </div><div><br></div><div>In the xml source you'd use something like line 13 of doc/common/section_keystone-sample-conf-files.xml:</div>
<div>
<p class=""><span class=""><xi:include</span><span class=""> parse</span><span class="">=</span>"text"<span class=""> href</span><span class="">=</span>"<a href="http://git.openstack.org/cgit/openstack/keystone/plain/etc/keystone.conf.sample">http://git.openstack.org/cgit/openstack/keystone/plain/etc/keystone.conf.sample</a>"<span class="">/></span></p>
</div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex"><div bgcolor="#FFFFFF" text="#000000"><div class="">
<br>
<br>
<blockquote 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></div>
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)<div class=""><br></div></div></blockquote><div><br></div><div>That's great, we have an End User Guide at <a href="http://docs.openstack.org/user-guide/content/">http://docs.openstack.org/user-guide/content/</a>.</div>
<div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex"><div bgcolor="#FFFFFF" text="#000000"><div class="">
<br>
<blockquote 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></div>
I think not, Heat is a layer above API/SDK.<div class=""><br>
<blockquote 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></div>
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></div></blockquote><div><br></div><div><div>I have a few ideas for potential resources to help you, let's chat tomorrow on IRC. I think this placement in the end user guide makes a lot of sense -- Dashboard, CLI users would definitely want to get started with heat templates.</div>
<div><br></div><div>Anne</div></div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex"><div bgcolor="#FFFFFF" text="#000000">
<br>
[1] <a href="http://docs.openstack.org/developer/heat/template_guide/" target="_blank">http://docs.openstack.org/developer/heat/template_guide/</a><br>
</div>
<br>_______________________________________________<br>
OpenStack-dev mailing list<br>
<a href="mailto:OpenStack-dev@lists.openstack.org">OpenStack-dev@lists.openstack.org</a><br>
<a href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev" target="_blank">http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev</a><br>
<br></blockquote></div><br></div></div>