Open Stack

On Thu, May 15, 2014 at 11:32 AM, Steve Baker <sbaker at redhat.com> wrote:

> On 15/05/14 11:54, Gauvain Pocentek wrote:
> > (Resending to add openstack-dev)
> >
> > Gauvain Pocentek
> >
> > Objectif Libre - Infrastructure et Formations Linux
> > http://www.objectif-libre.com
> >
> > Le 2014-05-15 17:34, Gauvain Pocentek a écrit :
> >> 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'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.

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'd also like input on the loss of features I'm describing above. Is this
worth experimenting with?

Thanks,
Anne


>  >> I've drafted a spec to keep track of this at [0].
> >>
> >> Let me know if this sounds OK to you all.
> >>
> >> Gauvain Pocentek
> >>
> >> Objectif Libre - Infrastructure et Formations Linux
> >> http://www.objectif-libre.com
> >>
> >> [0]:
> >> https://blueprints.launchpad.net/openstack-manuals/+spec/heat-templates
> >>
> Thanks for raising this, I do hope I can help writing the content. In
> addition to this, we will at some point need to port the resource
> reference generation to this guide as well.
>
> _______________________________________________
> OpenStack-dev mailing list
> OpenStack-dev at lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20140516/730aa3d7/attachment.html>