<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 22/02/14 06:42, Mike Spreitzer
wrote:<br>
</div>
<blockquote
cite="mid:OF01EBEF44.3D7BF2FA-ON85257C86.0060CEC8-85257C86.00614090@us.ibm.com"
type="cite"><tt><font size="2">Zane Bitter
<a class="moz-txt-link-rfc2396E" href="mailto:zbitter@redhat.com"><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 size="2">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 size="2"><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 size="2">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"><tt><font
size="2">https://bugs.launchpad.net/openstack-manuals/+bug/1281691</font></tt></a>
<br>
</blockquote>
<meta http-equiv="content-type" content="text/html;
charset=ISO-8859-1">
<p style="margin: 0px 0px 0.8em; padding: 0px; width: auto;
max-width: 45em; color: rgb(51, 51, 51); font-family: 'Ubuntu
Mono', monospace; font-size: 11.818181991577148px; font-style:
normal; font-variant: normal; font-weight: normal; letter-spacing:
normal; line-height: 18px; orphans: auto; text-align: left;
text-indent: 0px; text-transform: none; white-space: normal;
widows: auto; word-spacing: 0px; -webkit-text-stroke-width: 0px;
background-color: rgb(255, 255, 255);">I think the heat template
guide will always use sphinx since it autogenerates the resource
reference section by introspecting the heat codebase.</p>
<p style="margin: 0px 0px 0.8em; padding: 0px; width: auto;
max-width: 45em; color: rgb(51, 51, 51); font-family: 'Ubuntu
Mono', monospace; font-size: 11.818181991577148px; font-style:
normal; font-variant: normal; font-weight: normal; letter-spacing:
normal; line-height: 18px; orphans: auto; text-align: left;
text-indent: 0px; text-transform: none; white-space: normal;
widows: auto; word-spacing: 0px; -webkit-text-stroke-width: 0px;
background-color: rgb(255, 255, 255);">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 style="margin: 0px 0px 0.8em; padding: 0px; width: auto;
max-width: 45em; color: rgb(51, 51, 51); font-family: 'Ubuntu
Mono', monospace; font-size: 11.818181991577148px; font-style:
normal; font-variant: normal; font-weight: normal; letter-spacing:
normal; line-height: 18px; orphans: auto; text-align: left;
text-indent: 0px; text-transform: none; white-space: normal;
widows: auto; word-spacing: 0px; -webkit-text-stroke-width: 0px;
background-color: rgb(255, 255, 255);">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 style="margin: 0px 0px 0.8em; padding: 0px; width: auto;
max-width: 45em; color: rgb(51, 51, 51); font-family: 'Ubuntu
Mono', monospace; font-size: 11.818181991577148px; font-style:
normal; font-variant: normal; font-weight: normal; letter-spacing:
normal; line-height: 18px; orphans: auto; text-align: left;
text-indent: 0px; text-transform: none; white-space: normal;
widows: auto; word-spacing: 0px; -webkit-text-stroke-width: 0px;
background-color: rgb(255, 255, 255);">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>
</body>
</html>