On Sun, Feb 23, 2014 at 2:14 PM, Steve Baker <sba...@redhat.com> wrote:
> On 24/02/14 08:44, Anne Gentle wrote: > > > > > 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. > > 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 pull from heat-templates files directly. In the xml source you'd use something like line 13 of doc/common/section_keystone-sample-conf-files.xml: <xi:include parse="text" href=" http://git.openstack.org/cgit/openstack/keystone/plain/etc/keystone.conf.sample "/> > > > 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) > > That's great, we have an End User Guide at http://docs.openstack.org/user-guide/content/. > > 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. > I have a few ideas for potential resources to help you, let's chat tomorrow on IRC. I think this placement in the end user guide makes a lot of sense -- Dashboard, CLI users would definitely want to get started with heat templates. Anne > > [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 > >
_______________________________________________ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
