<div dir="ltr">I have a couple of thoughts -- sorry it took me a while to sort through and reply.<br><div><div class="gmail_extra"><br><br><div class="gmail_quote">On Mon, Feb 11, 2013 at 7:54 AM, Lorin Hochstein <span dir="ltr"><<a href="mailto:lorin@nimbisservices.com" target="_blank">lorin@nimbisservices.com</a>></span> wrote:<br>
<blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"><div dir="ltr"><br><div class="gmail_extra"><div class="gmail_quote"><div class="im">On Mon, Feb 11, 2013 at 2:38 AM, Atul Jha <span dir="ltr"><<a href="mailto:Atul.Jha@csscorp.com" target="_blank">Atul.Jha@csscorp.com</a>></span> wrote:<br>
<blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">Lorin,<br>
<br>
<a href="http://docs.openstack.org/folsom/openstack-compute/admin/content/ch_installing-openstack-compute.html" target="_blank">http://docs.openstack.org/folsom/openstack-compute/admin/content/ch_installing-openstack-compute.html</a> </blockquote>
<blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
<a href="http://docs.openstack.org/folsom/openstack-compute/admin/content/configuring-openstack-compute-basics.html" target="_blank">http://docs.openstack.org/folsom/openstack-compute/admin/content/configuring-openstack-compute-basics.html</a><br>
<br></blockquote><div><br></div></div><div><div>I didn't even realize there was a chapter on "Installing OpenStack Compute" in the admin guide. Yeah, I'd support migrating this content out of the admin guide and into the install guides.</div>
</div><div><br></div><div>Take care,</div><div><br></div><div>Lorin</div><div><div class="h5"><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
________________________________________<br>
<br>
From: Lorin Hochstein [<a href="mailto:lorin@nimbisservices.com" target="_blank">lorin@nimbisservices.com</a>]<br>
Sent: Monday, February 11, 2013 3:38 AM<br>
To: Atul Jha<br>
Cc: <a href="mailto:openstack-docs@lists.openstack.org" target="_blank">openstack-docs@lists.openstack.org</a><br>
Subject: Re: [Openstack-docs] Restructuring OpenStack-doc for Grizzly<br>
<br>
Hi Atul:<br>
<div><div><br>
<br>
On Wed, Feb 6, 2013 at 2:59 AM, Atul Jha <<a href="mailto:Atul.Jha@csscorp.com" target="_blank">Atul.Jha@csscorp.com</a><mailto:<a href="mailto:Atul.Jha@csscorp.com" target="_blank">Atul.Jha@csscorp.com</a>>> wrote:<br>
Hi All,<br>
<br>
I had a suggestion and wanted to put forward.<br>
<br>
Currently our complete doc structure looks like this<br>
<br>
Installing OS<br>
-- Contains install information on Ubuntu and Fedora<br>
Running OS<br>
-- Contains concepts about OS components and install steps as well for Debian/Suse/Ubunu/Fedora to some extent<br>
Developing OS<br>
OS CLI<br>
OS API<br>
Glossary<br>
<br></div></div></blockquote></div></div></div></div></div></blockquote><div><br></div><div>I think we are going to need to go to:<br></div><div>Installing <br></div><div>Configuring<br>Running<br><br>especially for the Compute subsystem, and very likely for the Storage and Networking categories too.<br>
</div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"><div dir="ltr"><div class="gmail_extra"><div class="gmail_quote"><div><div class="h5">
<blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"><div><div>
<br>
Will it be good idea to restructure Running OS and Installing OS this way<br>
<br>
Installing OS<br>
-- On Ubuntu<br>
-- Basic<br>
-- Advanced<br>
<br>
-- On Redhat/Centos/Fedora<br>
-- Basic<br>
-- Advanced<br>
-- On Other OS<br>
-- Basic<br>
-- Advance<br>
<br>
Too an extent its already existing, my real concern is with the "Running OS" part which has overlapping contents as in install instructions.<br>
<br></div></div></blockquote></div></div></div></div></div></blockquote><div><br></div><div>I've looked at other large services and how they're documented and I think that the only operating system split I see repeatedly is Linux and Windows. (We'll need to add Windows - I'm surprised the Hyper-V team hasn't submitted a patch yet.)<br>
<br></div><div>I think that the "other" is going to become a full-fledged SUSE guide, they say they are working on it. <br><br></div><div>It's fairly straightforward to continue with our use of conditional text to do this. I think "Configuring" is the biggest difference though, I'm not sure day-to-day running has many differences across operating systems. But I'm sure I'll find out soon at the upcoming Book Sprint.<br>
</div><div><br></div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"><div dir="ltr"><div class="gmail_extra"><div class="gmail_quote"><div>
<div class="h5"><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"><div><div>
Keeping Nova/Swift/Quantum guide with conf files and basic concepts behind it and updating it on regular basis will be much better. Lets take compute admin guide for example. I find it like having too much data and to an extent replication of our Install OS components in it.<br>
<br>
Compute administration guide<br>
-- Concept of nova<br>
-- Architecture<br>
-- Hypervisor based config change<br>
-- Available config flags<br>
<br>
<br></div></div></blockquote></div></div></div></div></div></blockquote><div><br></div><div>I think that we'll eventually get rid of "administration" guides and replace with "configuring" and "running" -- the Operator's manual is going to help us with some of this. We'll have that in three weeks.<br>
</div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"><div dir="ltr"><div class="gmail_extra"><div class="gmail_quote"><div><div class="h5">
<blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"><div><div>
What do you guys think?<br>
<br></div></div></blockquote></div></div></div></div></div></blockquote><div><br></div><div>I think the bug logged at <a href="https://bugs.launchpad.net/openstack-manuals/+bug/1110137">https://bugs.launchpad.net/openstack-manuals/+bug/1110137</a> captures the fact that we've exhausted the usefulness of "administration" as a descriptor for what you have to do to run OpenStack. Lorin has a great start at an explanation that will be used in the Operator's guide that should help immensely. Also to address the issues raised in this bug, I've asked Diane Fleming to start outlining what a refactor should look like to get the Admin guide more manageable.<br>
<br></div><div>To summarize:<br></div><div>A refactor should make install/configure/run separate<br></div><div>A refactor should continue to point out differences between ubuntu/RHEL/Suse ideally using the conditional mechanism we have in the install guide today (though of course improvements are welcomed). <br>
<br>I agree with Lorin's assessment. Sounds like you could submit a patch that fixes the Install chapter from the Admin manual as a starting point if that's what's bothersome. Gotta start somewhere. <br><br>Thanks for bringing it up -<br>
Anne<br></div><div><br></div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"><div dir="ltr"><div class="gmail_extra"><div class="gmail_quote">
<div><div class="h5"><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"><div><div>
Can you give an example of some content that currently is in the compute admin guide that you think shouldn't be there because of the overlap with the installation manuals?<br>
<br>
I'm not opposed to a refactor on principle, but I also worry about users needing to jump around across many different manuals, because the current task they are trying to perform cuts across multiple doc guides. I think some content overlap might be unavoidable. If you could provide some specific examples about content that you recommend be removed from the admin guide, it would help me understand this better.<br>
<br>
Take care,<br>
<br>
Lorin<br>
<br>
--<br>
Lorin Hochstein<br>
Lead Architect - Cloud Services<br>
Nimbis Services, Inc.<br>
</div></div><a href="http://www.nimbisservices.com" target="_blank">www.nimbisservices.com</a><<a href="http://www.nimbisservices.com" target="_blank">http://www.nimbisservices.com</a>><br>
<a href="http://www.csscorp.com/common/email-disclaimer.php" target="_blank">http://www.csscorp.com/common/email-disclaimer.php</a><br>
</blockquote></div></div></div><div><div class="h5"><br><br clear="all"><div><br></div>-- <br><div dir="ltr">Lorin Hochstein<br><div>Lead Architect - Cloud Services</div><div>Nimbis Services, Inc.</div><div><a href="http://www.nimbisservices.com" target="_blank">www.nimbisservices.com</a></div>
</div>
</div></div></div></div>
<br>_______________________________________________<br>
Openstack-docs mailing list<br>
<a href="mailto:Openstack-docs@lists.openstack.org">Openstack-docs@lists.openstack.org</a><br>
<a href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs" target="_blank">http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs</a><br>
<br></blockquote></div><br></div></div></div>