<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: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 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">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>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>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>Do you have a resource in mind to put this together? </div>
<div><br></div><div>Anne</div><div><br></div><div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">_______________________________________________<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>