Open Stack

Thanks Shaun - choose your own adventure is exactly what we would like after giving them a basic working stack.

Lorin, the Summit discussions around install docs are what led to a few Board members strongly stating we must have official install docs. Shaun is starting the work now.

Anne Gentle
Content Stacker
anne at openstack.org


On Jul 11, 2013, at 9:16 AM, Shaun McCance <shaunm at gnome.org> wrote:

> On Wed, 2013-07-10 at 15:46 +1000, Tom Fifield wrote:
>> On 10/07/13 15:40, Andreas Jaeger wrote:
>>> On 07/10/2013 02:34 AM, Tom Fifield wrote:
>>>> I'll take a bullish line, which may not necessarily be achievable:
>>>> 
>>>> """
>>>> On the day that the press release for Havana is sent out, we need -by
>>>> hook or by crook!- to have installation instructions for RHEL and
>>>> Ubuntu, and ideally SUSE and Debian too.
>>>> """
>>> 

I'd like as many helpers on this as possible and focus on this effort. Andreas it sounds like you want to make this happen for SUSE. 

Do we stop single sourcing with conditions for each op sys?

>>> What kind of instructions are you looking at? The "Basic installation"
>>> ones, the current "installation guides" - or both?
>>> 

I think we want one guide that starts simple and goes to complex with multiple example architectures. Note this is the opposite of what we have been doing so far.

>>> Andreas
>> 
>> Thanks for the reply!!
>> 
>> I think the answer is: "something" ;)
>> 
>> My personal impression is:
>> * the basic install guide is too basic right now
>> * the install guides are too heavy
>> 

Heh. I think the basic is too complex because of the networking. But your eyes are fresh. 

I do agree that we aren't documenting pack stack or open center or any number of other installers. We are teaching ways to install and configure OpenStack which means at least 4-6 architectures. Shaun is that your sense of the scope of the example adventures/arch?

>> so ideally what I would be looking for as a deployer is something that 
>> gives me a basic installation, with a bit of explanation on why the 
>> steps are being taken.
>> 
>> 
>> However, I believe Shaun McCance is taking a very serious look at the 
>> installation guides right now and should be able to provide an 
>> authoritative answer.
> 
> That's more or less my impression. I don't like that there's two guides.
> It's asking readers to make an upfront decision that they're probably
> not in a position to make. My preference would be a single install guide
> that's structured such that you get a basic, working install within the
> first few chapters, and can choose your own adventure after that.
> 

+1

> The current full install guide feels random, like pieces were added to
> it over time without a lot of thought to the overall narrative. The
> basic install guide is nice for what it is. I'd just prefer it were
> incorporated into a larger work.
> 

+1

> And I believe very strongly that your docs should be ready on release
> day. They're part of your fanfare, and should be linked to from your
> marketing materials.
> 

I'm scared of this but we have to scope it for install docs at least, the board, technical committee, and especially the users expect it. 

I don't think all docs can be ready at release, the scope is too wide. There are 30+  docs on an Openstack.org domains. My current thinking is that we will have a set of release docs (install and config only) and a set of library books that are not manuals tied to a release but merely guides. We may need to publish elsewhere to make this line strongly drawn, but I'm not sure we are ready to do that type of curation.

This distinction is especially important as we must prove we can deliver docs at release time.

Thanks Shaun for the analysis!
Anne

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