On Sun, Feb 23, 2014 at 1:23 PM, Steve Baker <sba...@redhat.com> wrote:
> On 22/02/14 06:42, Mike Spreitzer wrote: > > Zane Bitter <zbit...@redhat.com> <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 > > Hi Steve, I hesitate to embrace option 1 because the Sphinx output would still live rather separately so I don't know how to provide a better experience to template developers that way. Now that we have a reliable git.openstack.org we often embed source from other project's repositories in openstack-manuals and the api-site repositories. Also realize the entire Configuration Reference is programmatically pulled from five OpenStack repositories already. It would be great to add a chapter about template authoring to an existing guide. The template developers, are they cloud admins or end users more likely? Or maybe Mike, Quiming, or Zane has another idea -- do you think it has to be a separate guide completely? Another idea is that we're putting together a new API and SDK landing page in the coming month, would this user be most likely to visit that? Do you have a resource in mind to put this together? Anne > _______________________________________________ > OpenStack-dev mailing list > OpenStack-dev@lists.openstack.org > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev > >
_______________________________________________ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
