<div dir="ltr"><br><div class="gmail_extra"><br><br><div class="gmail_quote">On Thu, May 15, 2014 at 10:34 AM, Gauvain Pocentek <span dir="ltr"><<a href="mailto:gauvain.pocentek@objectif-libre.com" target="_blank">gauvain.pocentek@objectif-libre.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">Hello,<br>
<br>
This mail probably mainly concerns the doc team, but I guess that the heat team wants to know what's going on.<br>
<br>
We've shortly discussed the state of heat documentation with Anne Gentle and Andreas Jaeger yesterday, and I'd like to share what we think would be nice to do.<br>
<br>
Currently we only have a small section in the user guide that describes how to start a stack, but nothing documenting how to write templates. The heat developer doc provides a good reference, but I think it's not easy to use to get started.<br>


<br>
So the idea is to add an "OpenStack Orchestration" chapter in the user guide that would document how to use a cloud with heat, and how to write templates.<br>
<br>
I've drafted a spec to keep track of this at [0].<br>
<br></blockquote><div><br></div><div><div style="font-family:arial,sans-serif;font-size:12.727272033691406px">I'd like to experiment a bit with converting the End User Guide to an easier markup to enable more contributors to it. Perhaps bringing in Orchestration is a good point to do this, plus it may help address the auto-generation Steve mentions. </div>

<div style="font-family:arial,sans-serif;font-size:12.727272033691406px"><br></div><div style="font-family:arial,sans-serif;font-size:12.727272033691406px">The loss would be the single sourcing of the End User Guide and Admin User Guide as well as loss of PDF output and loss of translation. If these losses are worthwhile for easier maintenance and to encourage contributions from more cloud consumers, then I'd like to try an experiment with it.</div>

<div style="font-family:arial,sans-serif;font-size:12.727272033691406px"><br></div><div style="font-family:arial,sans-serif;font-size:12.727272033691406px">The experiment would be to have a new repo set up, openstack/user-guide and use the docs-core team as reviewers on it. Convert the End User Guide from DocBook to RST and build with Sphinx. Use the oslosphinx tempate for output. But what I don't know is if it's possible to build the automated output outside of the openstack/heat repo, does anyone have interest in doing a proof of concept on this? </div>

<div style="font-family:arial,sans-serif;font-size:12.727272033691406px"><br></div><div style="font-family:arial,sans-serif;font-size:12.727272033691406px">I'd also like input on the loss of features I'm describing above. Is this worth experimenting with?</div>

<div style="font-family:arial,sans-serif;font-size:12.727272033691406px"><br></div><div style="font-family:arial,sans-serif;font-size:12.727272033691406px">Thanks,</div><div style="font-family:arial,sans-serif;font-size:12.727272033691406px">

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">
Let me know if this sounds OK to you all.<br>
<br>
Gauvain Pocentek<br>
<br>
Objectif Libre - Infrastructure et Formations Linux<br>
<a href="http://www.objectif-libre.com" target="_blank">http://www.objectif-libre.com</a><br>
<br>
[0]: <a href="https://blueprints.launchpad.net/openstack-manuals/+spec/heat-templates" target="_blank">https://blueprints.launchpad.<u></u>net/openstack-manuals/+spec/<u></u>heat-templates</a><br>
<br>
______________________________<u></u>_________________<br>
Openstack-docs mailing list<br>
<a href="mailto:Openstack-docs@lists.openstack.org" target="_blank">Openstack-docs@lists.<u></u>openstack.org</a><br>
<a href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs" target="_blank">http://lists.openstack.org/<u></u>cgi-bin/mailman/listinfo/<u></u>openstack-docs</a><br>
</blockquote></div><br></div></div>