[openstack-dev] [docs] Re: Install guide testing

Doug Hellmann doug at doughellmann.com
Fri Aug 25 17:29:32 UTC 2017


Excerpts from Andreas Jaeger's message of 2017-08-25 16:05:41 +0200:
> On 2017-08-25 15:40, 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.
> 
> The introductory document needs little changes for each release, it will
> cover several releases. I just pushed two changes up to update that
> document.

Right. We should clean up the version number (either update it or not
show it) but we tried to retain only content that would change
very little or for which we could easily add operating system
version-specific conditionals to the steps.

> > 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.
> 
> https://review.openstack.org/497813

I've +2ed that patch as a good start. We've talked about documenting
some "constellation" configurations for setting up clouds with
different purposes running different services. That page may be a
good place to do that, or it may just be that we link to those
constellations when they are available elsewhere. We can figure out
the best way to do that when someone volunteers to do the work.

> > 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.
> 
> 
> We discussed this several times and found no good solution. In
> openstack-manuals we build several documents - this would complicate the
> project repos significantly. Also, there's so much duplication that
> skipping over distros is just a small part,

Yes, we're still open to suggestions but in the absence of a solution
we've placed a higher priority on the other remaining work.

Doug

> 
> Andreas
> 
> > Roger
> > 
> > [1] https://docs.openstack.org/install-guide/environment-messaging-obs.html
> > [2] https://bugs.launchpad.net/keystone/+bug/1712335
> > 
> > __________________________________________________________________________
> > OpenStack Development Mailing List (not for usage questions)
> > Unsubscribe: OpenStack-dev-request at lists.openstack.org?subject:unsubscribe
> > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
> > 
> 



More information about the OpenStack-dev mailing list