Open Stack

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 ;) ).

 

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.

 

With kind regards,

 

Bas Peters

 

From: annegentle at justwriteclick.com [mailto:annegentle at justwriteclick.com] On Behalf Of Anne Gentle
Sent: Thursday, October 2, 2014 4:40 PM
To: Matt Kassawara
Cc: Bas Peters; openstack-docs at lists.openstack.org
Subject: Re: [Openstack-docs] Questions regarding the degree of explanation in the openstack manuals

 

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.

 

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:

Operations Guide: http://docs.openstack.org/openstack-ops/content/openstack-ops_preface.html#who-this-book-is-for

 

Security Guide: http://docs.openstack.org/security-guide/content/introduction-to-openstack.html

 

Architecture Design Guide: http://docs.openstack.org/arch-design/content/arch-guide-intended-audience.html

 

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. 

 

Do you have suggestions for indicating that, perhaps with a section like the examples above?

 

Thanks,

Anne

 

 

On Thu, Oct 2, 2014 at 9:18 AM, Matt Kassawara <mkassawara at gmail.com <mailto:mkassawara at gmail.com> > wrote:

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.

 

On Thu, Oct 2, 2014 at 2:00 AM, Bas Peters <baspeters93 at gmail.com <mailto:baspeters93 at gmail.com> > wrote:

Dear all,

 

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.

 

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? 


With kind regards,

 

Bas

 

PS. Anyone attending Linuxcon/Cloudopen Europe soon?

 

_______________________________________________
Openstack-docs mailing list
Openstack-docs at lists.openstack.org <mailto:Openstack-docs at lists.openstack.org> 
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs

 


_______________________________________________
Openstack-docs mailing list
Openstack-docs at lists.openstack.org <mailto:Openstack-docs at lists.openstack.org> 
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs

 

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20141002/68160391/attachment-0001.html>