Open Stack

On 22/02/14 06:42, Mike Spreitzer wrote:
> Zane Bitter <zbitter at redhat.com> wrote on 02/21/2014 12:23:05 PM:
>
> > Yeah, we are overloading the term 'developer' here, since that section
> > contains both information that is only useful to developers working on
> > Heat itself, and information useful to users developing templates.
>
> 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.
>
> > I'm not sure if this is forced because of an OpenStack-wide assumption
> > that there is only API documentation and developer documentation?
> >
> > We ought to split these up and make the difference clear if we can.
>
> Forget the "if".  If we don't want to have to mentor every new user,
> we need decent documentation.
>
> https://bugs.launchpad.net/openstack-manuals/+bug/1281691

I think the heat template guide will always use sphinx since it
autogenerates the resource reference section by introspecting the heat
codebase.

Having it as a subdirectory of the developer guide was always meant to
be a temporary solution, I see a couple of options:

1. allow the heat repo to generate 2 separate sphinx documentation sets,
one developer docs and one template guide
2. move the template guide to openstack-manuals (or some other manual repo)

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

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20140224/218bb5fe/attachment.html>