Mailing-List: contact cloudstack-dev-help@incubator.apache.org; run by ezmlm
Precedence: bulk
Reply-To: cloudstack-dev@incubator.apache.org
Received-SPF: neutral (athena.apache.org: local policy)
Message-ID: <4FF0037E.40503@widodh.nl>
Date: Sun, 01 Jul 2012 09:59:58 +0200
From: Wido den Hollander <wido@widodh.nl>
User-Agent: Mozilla/5.0 (X11; Linux x86_64;
 rv:13.0) Gecko/20120615 Thunderbird/13.0.1
MIME-Version: 1.0
To: cloudstack-dev@incubator.apache.org
Subject: Re: Runbook for a very small setup
References: 
 <CAKprHVZrVSRUbyrShy0RdvkUuFp7VJRGCezJUhV_PhOMCEvPRw@mail.gmail.com>
 <4FEF0985.3050903@widodh.nl>
 <CAKprHVaxfJgJMkme3NYK7F=wB4nxiNZaU1bNaw9jRwt=eoV94Q@mail.gmail.com>
In-Reply-To: 
 <CAKprHVaxfJgJMkme3NYK7F=wB4nxiNZaU1bNaw9jRwt=eoV94Q@mail.gmail.com>
Content-Type: text/plain; charset=ISO-8859-1; format=flowed
Content-Transfer-Encoding: 7bit


On 06/30/2012 07:39 PM, David Nalley wrote:
>> Looks great! Seems like an easy way for people to set up their first
>> cluster.
>>
>> Although I really do like this initiative, shouldn't we be cautious that we
>> are bringing up to much documentation?
>
> It is indeed a concern - too much documentation becomes un-maintained
> documentation. (such as the quick install guide that was once useful
> but has now fallen into disrepair)
>
>>
>> We already have a PDF where we explain people how to set up CloudStack. We
>> should prevent having multiple docs which might say different things :)
>
> So the best and worst of the existing install guide is that it's
> descriptive, and talks about every possible trip down the rabbit hole.
> That is good and bad - much like Linux - so many things that you can
> do, but for most people your first experience with Linux shouldn't
> involve custom compiling your kernel. That makes it descriptive rather
> than prescriptive - and it also assumes a large amount of knowledge in
> multiple domains (virtualization, networking, linux, etc) Those really
> are prereqs for success in deploying CloudStack, but precious few
> people possess all of the necessary knowledge in each of those
> domains. I fully expect the install guide to remain the canonical
> document - and I copied much from it (many thanks to Kevin, Jessica,
> and Radhika for their work on the document). I don't think that
> necessarily means that there is no place for things like the runbook
> though, provided that they remain maintained. (we should probably
> actively cull documents that aren't maintained for every major
> release.)

Ack. As long as stuff stays maintained I don't see a problem. We should 
just be aware of documents telling contradictions.

"The runbook says I should do A, but the Install Guide says B: Which one 
is right?"

Wido

>
> --David
>