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

Flavio Percoco flavio at redhat.com
Wed Mar 23 19:25:40 UTC 2016

On 23/03/16 15:00 -0400, Doug Hellmann wrote:
>Excerpts from Mike Perez's message of 2016-03-23 08:06:28 -0700:
>> 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
>> tent.
>> 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?
>This seems like a reasonable compromise. We can either handle them using
>separate manual repos, or as Julien points out we could include them in
>the tree with the code and publish them separately like we're doing with
>release notes.

I think merging it in tree and publsihing them separatedly (or collecting them
under the same link) would be better.

FWIW, Zaqar had the same issue as other projects and the team ended up merging
the guide in the tree.


>> [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
>OpenStack Development Mailing List (not for usage questions)
>Unsubscribe: OpenStack-dev-request at lists.openstack.org?subject:unsubscribe

Flavio Percoco
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 819 bytes
Desc: not available
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20160323/5fae080b/attachment.pgp>

More information about the OpenStack-dev mailing list