Open Stack

On Sun, Feb 23, 2014 at 2:14 PM, Steve Baker <sbaker at redhat.com> 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> wrote:
>
>>   On 22/02/14 06:42, Mike Spreitzer wrote:
>>
>> Zane Bitter <zbitter at redhat.com> <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 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 at lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20140223/a0ef8fc4/attachment.html>