Open Stack

On Fri, 25 Aug 2017 15:40:07 +0200
Roger Luethi wrote:

> I don't know what will get changed or created until the release, but
> what I can find right now in terms of installation instructions is this:
> 
> https://docs.openstack.org/pike/install/
> 
> leading to the "OpenStack Installation Tutorial":
> 
> https://docs.openstack.org/install-guide/
> 
> plus many project-specific instructions:
> 
> https://docs.openstack.org/<project_name>/pike/install/
> 
> The OpenStack Installation Tuturial is labelled "Installation Guide
> 15.0", same as Ocata (Newton was 0.1). The URL is not versioned, even
> though there will be changes between releases (the instructions for
> enabling the OpenStack repository are updated every release, and there
> are bound to be other differences). I wonder how that will be handled
> in the future.

So the install guide is not versioned from Pike on, by design, and
https://review.openstack.org/#/c/498197/ removed version numbers from
guide labels. Should be less confusing now, I hope.
 
> I have not read all of the new "OpenStack Installation Tutorial", but
> looking at the table of contents, there seems to be a gap between
> "Environment"->"Memcached" and "Launch an instance". Where do we tell the
> readers which project-specific guides to follow, and in what order? Both
> pieces of information are rather crucial for a successful installation.

That has been addressed in https://review.openstack.org/#/c/497813/ and
again in https://review.openstack.org/#/c/498539/. We now have pointers to
project guides and information on a minimal cloud deployment included in
between "Memcached" and "Launch an instance":

https://docs.openstack.org/install-guide/openstack-services.html
 
> I expect users will find confusing that clicking the "Next" arrow on a
> distro-specific page (say, [1]) will often take them to the same page,
> just for a different distro. In the keystone install-guide, clicking on
> the Next arrow can result in skipped pages (depending on the distro,
> e.g. [2]). I realize that distro-specific instructions are not easily
> implemented with the new setup, but maybe the doc team could suggest
> a way to handle distro-specific paths for all projects.

I actually liked the keystone guide structure but I agree that following the
Next links can be confusing to users. Issues like this are totally something
we could have a closer look at the PTG, if people are available on Thu.

Sign up at https://etherpad.openstack.org/p/docs-i18n-ptg-queens.

Thanks,
pk