On 24/02/14 08:44, Anne Gentle wrote: > > > > On Sun, Feb 23, 2014 at 1:23 PM, Steve Baker <sba...@redhat.com > <mailto:sba...@redhat.com>> wrote: > > On 22/02/14 06:42, Mike Spreitzer wrote: >> Zane Bitter <zbit...@redhat.com> <mailto: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 > <http://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. > If you could point me at some examples of where things are being pulled in from code repos into manuals then I'll take a look. Another repo which would be useful to pull from is heat-templates, which would allow us to store canonical example templates in one place, but include them in manuals.
> 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? > I would say end users. If you're doing anything OpenStack with CLIs or Horizon then you should consider automating that by authoring a Heat template. Feel free to suggest an existing manual the template guide could be added too. Currently we have mostly reference docs[1] but I'm hoping to spend a bunch of post-feature-freeze time to start some how-to recipe content (although that is what I said during havana freeze too) > 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? > I think not, Heat is a layer above API/SDK. > Do you have a resource in mind to put this together? I was hoping to spend some time just writing content rather than porting to docbook and reorganizing repos, but it looks like the time has come. [1] http://docs.openstack.org/developer/heat/template_guide/
_______________________________________________ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev