<html>
<head>
<meta content="text/html; charset=ISO-8859-1"
http-equiv="Content-Type">
</head>
<body text="#000000" bgcolor="#FFFFFF">
<div class="moz-cite-prefix">On 02/23/2014 01:14 PM, Steve Baker
wrote:<br>
</div>
<blockquote cite="mid:530A569A.2090702@redhat.com" type="cite">
<meta content="text/html; charset=ISO-8859-1"
http-equiv="Content-Type">
<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 moz-do-not-send="true" class="moz-txt-link-freetext"
href="http://docs.openstack.org/developer/heat/template_guide/">http://docs.openstack.org/developer/heat/template_guide/</a><br>
<br>
</blockquote>
Just to add to this a bit, some reviews have some in which want to
document the /contrib directory resources. I don't necessarily
think it makes sense for these to be in the main documentation, but
rather a cotrib resources document. I'm not sure how to make that
happen, but it seems to make the most sense to me.<br>
<br>
Another option is to mark resources in the documentation that are
contrib as such and indicate the cloud provider must enable them for
them to be usable.<br>
<br>
Regards,<br>
-steve<br>
<br>
<blockquote cite="mid:530A569A.2090702@redhat.com" type="cite">
<fieldset class="mimeAttachmentHeader"></fieldset>
<br>
<pre wrap="">_______________________________________________
OpenStack-dev mailing list
<a class="moz-txt-link-abbreviated" href="mailto:OpenStack-dev@lists.openstack.org">OpenStack-dev@lists.openstack.org</a>
<a class="moz-txt-link-freetext" href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev">http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev</a>
</pre>
</blockquote>
<br>
</body>
</html>