[openstack-dev] [docs] Our Install Guides Only Cover Defcore - What about big tent?

Mike Perez thingee at gmail.com
Wed Mar 23 15:06:28 UTC 2016

Hey all,

I've been talking to a variety of projects about lack of install guides. This
came from me not having a great experience with trying out projects in the big

Projects like Manila have proposed install docs [1], but they were rejected
by the install docs team because it's not in defcore. One of Manila's goals of
getting these docs accepted is to apply for the operators tag
ops:docs:install-guide [2] so that it helps their maturity level in the project
navigator [3].

Adrian Otto expressed to me having the same issue for Magnum. I think it's
funny that a project that gets keynote time at the OpenStack conference can't
be in the install docs personally.

As seen from the Manila review [1], the install docs team is suggesting these
to be put in their developer guide.

I don't think this is a great idea. Mainly because they are for developers,
operators aren't going to be looking in there for install information. Also the
Developer doc page [4] even states "This page contains documentation for Python
developers, who work on OpenStack itself".

The install docs team doesn't want to be swamped with everyone in big tent
giving them their install docs, to be verified, and eventually likely to be
maintained by the install docs team.

However, as an operator when I go docs.openstack.org under install guides,
I should know how to install any of the big tent projects. These are accepted
projects by the Technical Committee.

Lets consider the bigger picture of things here. If we don't make this
information accessible, projects have poor adoption and get less feedback
because people can't attempt to install them to begin reporting bugs.

Proposal: if the install docs team doesn't want them in the install docs repo
and instead to live in tree of the project itself before it's in defcore, can
we at least make the install guides for all big tent projects accessible
at docs.openstack.org under install guides?

[1] - https://review.openstack.org/#/c/213756/
[2] - http://git.openstack.org/cgit/openstack/ops-tags-team/tree/descriptions/ops-docs-install-guide.rst
[3] - http://www.openstack.org/software/releases/liberty/components/manila
[4] - http://docs.openstack.org/developer/openstack-projects.html

Mike Perez

More information about the OpenStack-dev mailing list