Open Stack

On 02/23/2014 01: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.
>
>> 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/
>
Just to add to this a bit, some reviews have some in which want to 
document the /contrib directory resources.  I don't necessarily think it 
makes sense for these to be in the main documentation, but rather a 
cotrib resources document.  I'm not sure how to make that happen, but it 
seems to make the most sense to me.

Another option is to mark resources in the documentation that are 
contrib as such and indicate the cloud provider must enable them for 
them to be usable.

Regards,
-steve

>
> _______________________________________________
> 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/f89e5c84/attachment.html>