<div dir="ltr"><div class="gmail_default" style="font-family:arial,helvetica,sans-serif"><span style="font-family:arial,sans-serif">On Wed, Mar 23, 2016 at 11:06 AM, Mike Perez </span><span dir="ltr" style="font-family:arial,sans-serif"><<a href="mailto:thingee@gmail.com" target="_blank">thingee@gmail.com</a>></span><span style="font-family:arial,sans-serif"> wrote:</span><br></div><div class="gmail_extra"><div class="gmail_quote"><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">Hey all,<br>
<br>
I've been talking to a variety of projects about lack of install guides. This<br>
came from me not having a great experience with trying out projects in the big<br>
tent.<br>
<br>
Projects like Manila have proposed install docs [1], but they were rejected<br>
by the install docs team because it's not in defcore. One of Manila's goals of<br>
getting these docs accepted is to apply for the operators tag<br>
ops:docs:install-guide [2] so that it helps their maturity level in the project<br>
navigator [3].<br>
<br>
Adrian Otto expressed to me having the same issue for Magnum. I think it's<br>
funny that a project that gets keynote time at the OpenStack conference can't<br>
be in the install docs personally.<br>
<br>
As seen from the Manila review [1], the install docs team is suggesting these<br>
to be put in their developer guide.<br>
<br>
I don't think this is a great idea. Mainly because they are for developers,<br>
operators aren't going to be looking in there for install information. Also the<br>
Developer doc page [4] even states "This page contains documentation for Python<br>
developers, who work on OpenStack itself".<br>
<br>
The install docs team doesn't want to be swamped with everyone in big tent<br>
giving them their install docs, to be verified, and eventually likely to be<br>
maintained by the install docs team.<br>
<br>
However, as an operator when I go <a href="http://docs.openstack.org" rel="noreferrer" target="_blank">docs.openstack.org</a> under install guides,<br>
I should know how to install any of the big tent projects. These are accepted<br>
projects by the Technical Committee.<br>
<br>
Lets consider the bigger picture of things here. If we don't make this<br>
information accessible, projects have poor adoption and get less feedback<br>
because people can't attempt to install them to begin reporting bugs.<br>
<br>
Proposal: if the install docs team doesn't want them in the install docs repo<br>
and instead to live in tree of the project itself before it's in defcore, can<br>
we at least make the install guides for all big tent projects accessible<br>
at <a href="http://docs.openstack.org" rel="noreferrer" target="_blank">docs.openstack.org</a> under install guides?<br>
<br>
<br>
[1] - <a href="https://review.openstack.org/#/c/213756/" rel="noreferrer" target="_blank">https://review.openstack.org/#/c/213756/</a><br>
[2] - <a href="http://git.openstack.org/cgit/openstack/ops-tags-team/tree/descriptions/ops-docs-install-guide.rst" rel="noreferrer" target="_blank">http://git.openstack.org/cgit/openstack/ops-tags-team/tree/descriptions/ops-docs-install-guide.rst</a><br>
[3] - <a href="http://www.openstack.org/software/releases/liberty/components/manila" rel="noreferrer" target="_blank">http://www.openstack.org/software/releases/liberty/components/manila</a><br>
[4] - <a href="http://docs.openstack.org/developer/openstack-projects.html" rel="noreferrer" target="_blank">http://docs.openstack.org/developer/openstack-projects.html</a><br></blockquote></div><div><br></div><div><div class="gmail_default" style="font-family:arial,helvetica,sans-serif">FWIW, the same issue applies to other official docs. In particular, I'm thinking of the networking guide.</div><div class="gmail_default" style="font-family:arial,helvetica,sans-serif"><br></div><div class="gmail_default"><font face="arial, helvetica, sans-serif"><a href="http://docs.openstack.org/liberty/networking-guide/">http://docs.openstack.org/liberty/networking-guide/</a></font><br></div><div class="gmail_default" style="font-family:arial,helvetica,sans-serif"><br></div><div class="gmail_default" style="font-family:arial,helvetica,sans-serif">The networking guide is *fantastic*, but it's limited to covering only ML2+OVS and ML2+LB. Coverage for other backends is currently considered out of scope, leaving no official place to put equivalent documentation except in dev docs.</div><div class="gmail_default" style="font-family:arial,helvetica,sans-serif"><br></div><div class="gmail_default" style="font-family:arial,helvetica,sans-serif">We got pushback on documenting OVN there, so we've been putting everything in our dev docs, instead. For example:</div><div class="gmail_default" style="font-family:arial,helvetica,sans-serif"><br></div><div class="gmail_default"><font face="arial, helvetica, sans-serif"><a href="http://docs.openstack.org/developer/networking-ovn/install.html">http://docs.openstack.org/developer/networking-ovn/install.html</a></font><br></div><div class="gmail_default"><font face="arial, helvetica, sans-serif"><a href="http://docs.openstack.org/developer/networking-ovn/refarch.html">http://docs.openstack.org/developer/networking-ovn/refarch.html</a><br></font></div><br></div><div><div class="gmail_default" style="font-family:arial,helvetica,sans-serif">It'd be nice to have somewhere else to publish these operator-oriented docs.</div></div><div><br></div>-- <br><div class="gmail_signature"><div dir="ltr"><div><font face="arial black, sans-serif">Russell Bryant</font></div></div></div>
</div></div>