Le 2014-05-16 17:13, Anne Gentle a écrit :
On Thu, May 15, 2014 at 10:34 AM, Gauvain Pocentek
<gauvain.pocen...@objectif-libre.com> wrote:
Hello,
This mail probably mainly concerns the doc team, but I guess that the
heat team wants to know what's going on.
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.
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.
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.
I've drafted a spec to keep track of this at [0].
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.
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.
Using RST would probably make it easier to import/include the
developers' documentation. But I'm not sure we can afford to loose the
features you mention. Translations for the user guides are very
important I think.
How would we review changes made in "external" repositories? The user
guides are continuously published, this means that a change done in the
heat/docs/ dir would quite quickly land on the webserver without a doc
team review. I completely trust the developers, but I'm not sure that
this is the way to go.
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?
I'm not sure that this is possible, but I'm no RST expert.
I'd also like input on the loss of features I'm describing above. Is
this worth experimenting with?
Starting this new book sounds like a lot of work. Right now I'm not
convinced it's worth it.
Gauvain
_______________________________________________
OpenStack-dev mailing list
OpenStack-dev@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
