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 <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.
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
_______________________________________________
OpenStack-dev mailing list
OpenStack-dev@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
