openstack team mailing list archive

[Stefano Maffulli <stefano@xxxxxxxxxxxxx>]

On 07/11/2013 11:58 PM, Jake G. wrote:
> <rant>
> Does anyone have installation instructions that a human being can
> actually understand and follow? 

Hi Jake, I think I understand what you're going through: the pain you're
reporting is unfortunately known and not rare.

The documentation team is aware that the installation instructions are
in urgent need for attention. The reasons for this technical debt is
that the documentation team has given priority to documenting the
general aspects of OpenStack. Writing an installation guide that is
general/generic for all sorts of possible combinations is too
complicated, so that task was given lower priority (the books like
Operations Guide and Security Guide were given higher priority, in case
you asked).

So, while knowing this won't help you ease your pain, I hope it sheds
some light on the reasons why the official installation documentation is
behind the rest of the docs.

To close the technical debt, Anne and the rest of the documentation team
will be working on a set of *opinionated* install guides. Acknowledging
that installing a complex system like OpenStack is (ahem) complex, what
makes it simpler is to make assumptions that reduce the variables. The
reasons why you see so many blog posts, small install guides, etc is
that these make assumptions to reduce the number of variables like: do I
use one or three or more nodes? nova network or neutron? swift? how to
configure keystone auth? what networking topology? where do I put the
dashboard? how about HA? etc

This is a call to anybody interested in documenting OpenStack
installation: join the documentation team and contribute your expertise
to write an *opinionated* guide to install OpenStack. It won't be the
ultimate guide to install OpenStack in all possible scenarios but it
will be a way to start.

https://wiki.openstack.org/wiki/Documentation
https://wiki.openstack.org/wiki/Documentation/HowTo

thanks
stef

-- 
Ask and answer questions on https://ask.openstack.org