On 22/02/14 06:42, Mike Spreitzer wrote: > Zane Bitter <zbit...@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
_______________________________________________ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
