<html xmlns:v="urn:schemas-microsoft-com:vml" xmlns:o="urn:schemas-microsoft-com:office:office" xmlns:w="urn:schemas-microsoft-com:office:word" xmlns:m="http://schemas.microsoft.com/office/2004/12/omml" xmlns="http://www.w3.org/TR/REC-html40"><head><meta http-equiv=Content-Type content="text/html; charset=utf-8"><meta name=Generator content="Microsoft Word 15 (filtered medium)"><style><!--
/* Font Definitions */
@font-face
{font-family:"Cambria Math";
panose-1:2 4 5 3 5 4 6 3 2 4;}
@font-face
{font-family:Calibri;
panose-1:2 15 5 2 2 2 4 3 2 4;}
/* Style Definitions */
p.MsoNormal, li.MsoNormal, div.MsoNormal
{margin:0cm;
margin-bottom:.0001pt;
font-size:12.0pt;
font-family:"Times New Roman","serif";}
a:link, span.MsoHyperlink
{mso-style-priority:99;
color:blue;
text-decoration:underline;}
a:visited, span.MsoHyperlinkFollowed
{mso-style-priority:99;
color:purple;
text-decoration:underline;}
span.E-mailStijl17
{mso-style-type:personal-reply;
font-family:"Calibri","sans-serif";
color:#1F497D;}
.MsoChpDefault
{mso-style-type:export-only;
font-family:"Calibri","sans-serif";
mso-fareast-language:EN-US;}
@page WordSection1
{size:612.0pt 792.0pt;
margin:70.85pt 70.85pt 70.85pt 70.85pt;}
div.WordSection1
{page:WordSection1;}
--></style><!--[if gte mso 9]><xml>
<o:shapedefaults v:ext="edit" spidmax="1026" />
</xml><![endif]--><!--[if gte mso 9]><xml>
<o:shapelayout v:ext="edit">
<o:idmap v:ext="edit" data="1" />
</o:shapelayout></xml><![endif]--></head><body lang=NL link=blue vlink=purple><div class=WordSection1><p class=MsoNormal><span lang=EN-US style='font-size:11.0pt;font-family:"Calibri","sans-serif";color:#1F497D;mso-fareast-language:EN-US'>To be honest, I think the way you just described the Openstack experience (of a first-timer) really covers the entire issue. Even though I agree with Matt that it doesn’t make much sense for someone without a decent knowledge of Linux system administration to start deploying clouds, I don’t think people generally care and just try anyways, following the guide as closely as possible. When something then deviates from what’s stated in the install guide I imagine a vast majority of these ‘newcomers’ don’t have a clue as to how to troubleshoot their setup (I think we can all recall that time ;) ).<o:p></o:p></span></p><p class=MsoNormal><span lang=EN-US style='font-size:11.0pt;font-family:"Calibri","sans-serif";color:#1F497D;mso-fareast-language:EN-US'><o:p> </o:p></span></p><p class=MsoNormal><span lang=EN-US style='font-size:11.0pt;font-family:"Calibri","sans-serif";color:#1F497D;mso-fareast-language:EN-US'>Do you think a preface containing some information on where to find help (MySQL docs, ask.openstack.org, stackexchange sites, distro-specific docs such as the RDO, etc.) would help more people get through the installation by their own means? Maybe a lot of people who want to just ‘try out’ Openstack could be referenced to Devstack instead in this preface.<o:p></o:p></span></p><p class=MsoNormal><span lang=EN-US style='font-size:11.0pt;font-family:"Calibri","sans-serif";color:#1F497D;mso-fareast-language:EN-US'><o:p> </o:p></span></p><p class=MsoNormal><span lang=EN-US style='font-size:11.0pt;font-family:"Calibri","sans-serif";color:#1F497D;mso-fareast-language:EN-US'>With kind regards,<o:p></o:p></span></p><p class=MsoNormal><span lang=EN-US style='font-size:11.0pt;font-family:"Calibri","sans-serif";color:#1F497D;mso-fareast-language:EN-US'><o:p> </o:p></span></p><p class=MsoNormal><span lang=EN-US style='font-size:11.0pt;font-family:"Calibri","sans-serif";color:#1F497D;mso-fareast-language:EN-US'>Bas Peters<o:p></o:p></span></p><p class=MsoNormal><span lang=EN-US style='font-size:11.0pt;font-family:"Calibri","sans-serif";color:#1F497D;mso-fareast-language:EN-US'><o:p> </o:p></span></p><p class=MsoNormal><b><span style='font-size:11.0pt;font-family:"Calibri","sans-serif"'>From:</span></b><span style='font-size:11.0pt;font-family:"Calibri","sans-serif"'> annegentle@justwriteclick.com [mailto:annegentle@justwriteclick.com] <b>On Behalf Of </b>Anne Gentle<br><b>Sent:</b> Thursday, October 2, 2014 4:40 PM<br><b>To:</b> Matt Kassawara<br><b>Cc:</b> Bas Peters; openstack-docs@lists.openstack.org<br><b>Subject:</b> Re: [Openstack-docs] Questions regarding the degree of explanation in the openstack manuals<o:p></o:p></span></p><p class=MsoNormal><o:p> </o:p></p><div><p class=MsoNormal>What Matt says is all true, but specific to Ubuntu/MySQL, there is no other OpenStack install guide for that particular user. So I think that there tend to be more questions for Ubuntu and also more "beginners" or "freshers" reading that particular guide. RHEL has another install guide, SUSE has another install guide. Debian has no other guide to my knowledge either but we don't see as many comments there.<o:p></o:p></p><div><p class=MsoNormal><o:p> </o:p></p></div><div><p class=MsoNormal>This is a nice analysis of the comments, for sure, thanks for looking at it and asking. We have a section in some books describing the audience and what their pre-requisite knowledge should be, for example:<o:p></o:p></p></div><div><p class=MsoNormal>Operations Guide: <a href="http://docs.openstack.org/openstack-ops/content/openstack-ops_preface.html#who-this-book-is-for">http://docs.openstack.org/openstack-ops/content/openstack-ops_preface.html#who-this-book-is-for</a><o:p></o:p></p></div><div><p class=MsoNormal><o:p> </o:p></p></div><div><p class=MsoNormal>Security Guide: <a href="http://docs.openstack.org/security-guide/content/introduction-to-openstack.html">http://docs.openstack.org/security-guide/content/introduction-to-openstack.html</a><o:p></o:p></p></div><div><p class=MsoNormal><o:p> </o:p></p></div><div><p class=MsoNormal>Architecture Design Guide: <a href="http://docs.openstack.org/arch-design/content/arch-guide-intended-audience.html">http://docs.openstack.org/arch-design/content/arch-guide-intended-audience.html</a><o:p></o:p></p></div><div><p class=MsoNormal><o:p> </o:p></p></div><div><p class=MsoNormal>For the Install Guides, that audience analysis has been done many times in the past years, and we mostly come up with this type of statement: "This guide enables you to choose your own OpenStack adventure using a combination of basic and optional services." This statement gets various reactions but I think it's pretty close to truth: installing OpenStack is an adventure that many take, and we document it for a few happy paths with a lot of assumption about what people should know before going on the adventure. <o:p></o:p></p></div><div><p class=MsoNormal><o:p> </o:p></p></div><div><p class=MsoNormal>Do you have suggestions for indicating that, perhaps with a section like the examples above?<o:p></o:p></p></div><div><p class=MsoNormal><o:p> </o:p></p></div><div><p class=MsoNormal>Thanks,<o:p></o:p></p></div><div><p class=MsoNormal>Anne<o:p></o:p></p></div><div><p class=MsoNormal> <o:p></o:p></p></div></div><div><p class=MsoNormal><o:p> </o:p></p><div><p class=MsoNormal>On Thu, Oct 2, 2014 at 9:18 AM, Matt Kassawara <<a href="mailto:mkassawara@gmail.com" target="_blank">mkassawara@gmail.com</a>> wrote:<o:p></o:p></p><blockquote style='border:none;border-left:solid #CCCCCC 1.0pt;padding:0cm 0cm 0cm 6.0pt;margin-left:4.8pt;margin-right:0cm'><div><p class=MsoNormal>I hope most people installing OpenStack have at least a basic amount of Linux systems administration experience. However, after some previous banter on this topic, we still tend to provide the actual commands for steps requiring basic experience (e.g., symlinks). On the other hand, networking steps get tricky because most people installing OpenStack for the first time lack network administration experience, especially on Linux with bridges, iptables, namespaces, etc.<o:p></o:p></p></div><div><p class=MsoNormal><o:p> </o:p></p><div><div><div><p class=MsoNormal>On Thu, Oct 2, 2014 at 2:00 AM, Bas Peters <<a href="mailto:baspeters93@gmail.com" target="_blank">baspeters93@gmail.com</a>> wrote:<o:p></o:p></p></div></div><blockquote style='border:none;border-left:solid #CCCCCC 1.0pt;padding:0cm 0cm 0cm 6.0pt;margin-left:4.8pt;margin-right:0cm'><div><div><div><div><p class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto'>Dear all,<o:p></o:p></p><p class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto'> <o:p></o:p></p><p class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto'><span lang=EN-US>As I’m new to the openstack project, I’m having some problems regarding the degree of explanation required in the Openstack install guides. In Havana/Icehouse, there are a lot of questions by people on very elementary things anyone having worked with linux for some time at least semi-professionally should/would know. For instance, in the Havana release, most noticeably in the Ubuntu section for some reason, there are a lot of comments regarding the setting up of MySQL. A bit of Googling would be able to answer most of these questions, but in my opinion the reason they are asked in the first place is because it’s not clear to people just by reading the docs.</span><o:p></o:p></p><p class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto'><span lang=EN-US> </span><o:p></o:p></p><p class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto'><span lang=EN-US>My question therefore is: To what degree should things be explained in the install guides? Is there a policy that I can find somewhere (I tried looking for it, but to no avail) regarding the depth of explanation? </span><o:p></o:p></p><p class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto'><span lang=EN-US><br>With kind regards,</span><o:p></o:p></p><p class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto'><span lang=EN-US style='color:#888888'> </span><span style='color:#888888'><o:p></o:p></span></p><p class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto'><span lang=EN-US style='color:#888888'>Bas</span><span style='color:#888888'><o:p></o:p></span></p><p class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto'><span lang=EN-US> </span><o:p></o:p></p><p class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto'><span lang=EN-US>PS. Anyone attending Linuxcon/Cloudopen Europe soon?</span><o:p></o:p></p></div></div><p class=MsoNormal><o:p> </o:p></p></div></div><p class=MsoNormal style='margin-bottom:12.0pt'>_______________________________________________<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" target="_blank">http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs</a><o:p></o:p></p></blockquote></div><p class=MsoNormal><o:p> </o:p></p></div><p class=MsoNormal style='margin-bottom:12.0pt'><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><o:p></o:p></p></blockquote></div><p class=MsoNormal><o:p> </o:p></p></div></div></body></html>