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