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

Reply via email to