Open Stack

On 24/02/14 08:44, Anne Gentle wrote:
>
>
>
> On Sun, Feb 23, 2014 at 1:23 PM, Steve Baker <sbaker at redhat.com
> <mailto:sbaker at redhat.com>> wrote:
>
>     On 22/02/14 06:42, Mike Spreitzer wrote:
>>     Zane Bitter <zbitter at redhat.com> <mailto:zbitter at 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/
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20140224/eb293053/attachment.html>