Open Stack

Le 2014-05-16 17:13, Anne Gentle a écrit :
> On Thu, May 15, 2014 at 10:34 AM, Gauvain Pocentek
> <gauvain.pocentek at 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