Open Stack

On 02/23/2014 09:14 PM, Steve Baker wrote:
> 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.

One way is something like doc/common/section_keystone-sample-conf-files.xml:

            <para><programlisting language="ini"><xi:include
parse="text"
href="http://git.openstack.org/cgit/openstack/keystone/plain/etc/logging.conf.sample"/></programlisting></para>


>> 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)

We could also add an introduction/overview to one of the guides with a
smallish example and give a link to the template guide from there.

>> 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/

Andreas
-- 
 Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi
  SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 Nürnberg, Germany
   GF: Jeff Hawn,Jennifer Guild,Felix Imendörffer,HRB16746 (AG Nürnberg)
    GPG fingerprint = 93A3 365E CE47 B889 DF7F  FED1 389A 563C C272 A126