<div dir="ltr"><div>I think our audience is most familiar and comfortable with distribution packages. Although not perfect, packages let our audience focus on the OpenStack configuration necessary to launch a VM rather than fumbling through Python dependencies, building init scripts, getting rootwrap working, etc. I think we need to pursue documenting a source installation option, but probably make it cater to people who want to take the next step toward customizing and automating a production deployment. In other words, the source installation option should consider an audience with more experience and therefore contain somewhat general instructions that require less extensive testing for each release.</div><div><br></div><div>In addition to using packages, maintaining a consistent structure for each service also benefits our audience because they can glean configuration similarities among services... perhaps simply through repetition. For example... create the SQL database, create Identity service entities, install packages, configure the service, synchronize database schema, start the service, and verify operation of the service. Allowing projects to provide installation content outside of the central installation guide primarily impacts the consistent structure, but also impacts the ability for the installation guide team (already very small and stretched very thin) to continue maintaining the guide in a proactive fashion by validating it prior to each release rather than waiting for our audience to open bugs, become frustrated, and ultimately decide against using OpenStack. The installation guide is usually the first thing newcomers stumble upon and a great experience benefits everyone.</div><div><br></div></div><div class="gmail_extra"><br><div class="gmail_quote">On Tue, Dec 8, 2015 at 10:27 AM, Anne Gentle <span dir="ltr"><<a href="mailto:annegentle@justwriteclick.com" target="_blank">annegentle@justwriteclick.com</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div dir="ltr"><br><div class="gmail_extra"><br><div class="gmail_quote"><span class="">On Tue, Dec 8, 2015 at 10:05 AM, Matt Kassawara <span dir="ltr"><<a href="mailto:mkassawara@gmail.com" target="_blank">mkassawara@gmail.com</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div dir="ltr">I think maintaining consistency and addressing issues becomes a problem if each project contains its own installation procedures.</div></blockquote><div><br></div></span><div>Okay, let's describe this system further. So for you the bar would be packaging resources for all four distros? Then you'd support a second install guide dir in the openstack-manuals repo? Or additional chapters in the existing install guide? </div><div><br></div><div>Can you discuss at the next install team meeting and let us know the team's recommendations for defining the inclusion -- what, where, by when, and how? Also does the install team envision being able to activate on this for the mitaka release? Is there a deadline for when packages would need to be tested, for example? We need to give Ben and other teams guidance by milestone-2, mid-January, if possible.</div><div><br></div><div>I can support what the install guide team thinks is possible, once I understand it.</div><div><br></div><div>Thanks,</div><div>Anne</div><div><div class="h5"><div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div><div><div class="gmail_extra"><br><div class="gmail_quote">On Tue, Dec 8, 2015 at 8:13 AM, Anne Gentle <span dir="ltr"><<a href="mailto:annegentle@justwriteclick.com" target="_blank">annegentle@justwriteclick.com</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div dir="ltr"><br><div class="gmail_extra"><br><div class="gmail_quote"><div><div>On Mon, Dec 7, 2015 at 1:44 PM, Ben Swartzlander <span dir="ltr"><<a href="mailto:ben@swartzlander.org" target="_blank">ben@swartzlander.org</a>></span> wrote:<br><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"><span>On 12/07/2015 10:42 AM, Anne Gentle wrote:<br>
</span><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"><span>
<br>
<br>
On Mon, Dec 7, 2015 at 9:36 AM, Ben Swartzlander <<a href="mailto:ben@swartzlander.org" target="_blank">ben@swartzlander.org</a><br></span><span>
<mailto:<a href="mailto:ben@swartzlander.org" target="_blank">ben@swartzlander.org</a>>> wrote:<br>
<br>
Hello docs team, when we submitted the install guide for Manila [1]<br>
in Liberty it was rejected because at the time only defcore projects<br>
were covered by the guide. Has that policy changed yet?<br>
<br>
<br>
I don't believe it will this release.<br>
<br>
If not, I would like to hear your recommendation for where the<br>
Manila install guide should go. The foundation's project navigator<br>
[2] counts the lack of an install guide as a mark against Manila.<br>
<br>
<br>
Have you published the RST files from that original patch from your own<br>
doc/source directory? That should count.<br>
</span></blockquote>
<br>
No we haven't. It's an option, but not one that I favor because we're trying to get all the docs (except dev docs) out of the code tree and into the manuals project where they belong.<br>
<br>
<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"><span>
I'm willing to resubmit the install guide content wherever it needs<br>
to go. Personally I'd like it to be part of the regular install<br>
guide, but if you have another idea please share it.<br>
<br>
<br>
Something I'd like to see implemented with a spec for doc tooling is this:<br>
1. Author install guide articles in your doc/source directory.<br>
2. Create a common TOC to pull many install guide articles together to<br>
build an install guide that goes beyond defcore projects to<br>
</span><a href="http://docs.openstack.org/" rel="noreferrer" target="_blank">docs.openstack.org/</a> <<a href="http://docs.openstack.org/" rel="noreferrer" target="_blank">http://docs.openstack.org/</a>><relname>/<distro>/<span><br>
3. Serve multiple users needs by building on existing install guide in a<br>
modular way without burdening the center.<br>
<br>
Do you have anyone who might want to take that idea on?<br>
</span></blockquote>
<br>
I like the above idea, but I would prefer to keep the actual source for the install guides in a centralized tree. We could call it the "extended install guide" or "install guide appendix" -- I don't really care. The point is to follow the same model we've been following with other guides and to do things similarly to how the existing install guide is done to facilitate an eventual merge (if the docs team decides to go that way).<br></blockquote><div><br></div></div></div><div>I'm not sure what the gain is for moving the source to a centralized tree. I think that the gain for keeping source where experts can review and test is the better path to high-quality content. </div><div><br></div><div>To me, there are a few resource limiters:</div><div><br></div><div>1. Packagers and packages for the distros we currently support: RHEL, Centos, OpenSUSE, SUSE Linux Enterprise Server, Ubuntu, and Debian.</div><div>2. Testers for the install instructions using packages and also integration with the "core" architecture.<br></div><div><div>3. Reviewers for the install content itself across all the distros who know manilla well.</div></div><div><br></div><div>How are you doing as far as coverage on the first two resources?</div><span><font color="#888888"><div><br></div><div>Anne</div></font></span><div><div><div> </div><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">
<br>
-Ben<br>
<br>
<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"><span>
Thanks,<br>
Anne<br>
<br>
<br>
-Ben Swartzlander<br>
Manila PTL<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://www.openstack.org/software/releases/liberty/components/manila" rel="noreferrer" target="_blank">http://www.openstack.org/software/releases/liberty/components/manila</a><br>
<br>
_______________________________________________<br>
OpenStack-docs mailing list<br>
<a href="mailto:OpenStack-docs@lists.openstack.org" target="_blank">OpenStack-docs@lists.openstack.org</a><br></span>
<mailto:<a href="mailto:OpenStack-docs@lists.openstack.org" target="_blank">OpenStack-docs@lists.openstack.org</a>><span><br>
<a href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs" rel="noreferrer" target="_blank">http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs</a><br>
<br>
<br>
<br>
<br>
--<br>
Anne Gentle<br>
Rackspace<br>
Principal Engineer<br>
</span><a href="http://www.justwriteclick.com" rel="noreferrer" target="_blank">www.justwriteclick.com</a> <<a href="http://www.justwriteclick.com" rel="noreferrer" target="_blank">http://www.justwriteclick.com</a>><br>
</blockquote><div><div>
<br>
<br>
_______________________________________________<br>
OpenStack-docs mailing list<br>
<a href="mailto:OpenStack-docs@lists.openstack.org" target="_blank">OpenStack-docs@lists.openstack.org</a><br>
<a href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs" rel="noreferrer" target="_blank">http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs</a><br>
</div></div></blockquote></div></div></div><div><div><br><br clear="all"><div><br></div>-- <br><div><div dir="ltr"><div>Anne Gentle</div><div>Rackspace</div><div>Principal Engineer</div><div><a href="http://www.justwriteclick.com" target="_blank">www.justwriteclick.com</a></div></div></div>
</div></div></div></div>
<br>_______________________________________________<br>
OpenStack-docs mailing list<br>
<a href="mailto:OpenStack-docs@lists.openstack.org" target="_blank">OpenStack-docs@lists.openstack.org</a><br>
<a href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs" rel="noreferrer" target="_blank">http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs</a><br>
<br></blockquote></div><br></div>
</div></div></blockquote></div></div></div><div><div class="h5"><br><br clear="all"><div><br></div>-- <br><div><div dir="ltr"><div>Anne Gentle</div><div>Rackspace</div><div>Principal Engineer</div><div><a href="http://www.justwriteclick.com" target="_blank">www.justwriteclick.com</a></div></div></div>
</div></div></div></div>
</blockquote></div><br></div>