Open Stack

Excerpts from Jeremy Stanley's message of 2017-07-27 22:07:33 +0000:
> On 2017-07-27 15:40:22 -0400 (-0400), Doug Hellmann wrote:
> [...]
> > Are we over-emphasizing the scale of the discovery problem?
> > 
> > When I search for how to install a package on Ubuntu (or Red Hat
> > or Debian for that matter), I find all sorts of references all over
> > the web (including on the sites for those distros) and I have to
> > sift through it all to find right command or package name to use
> > for my version.  Usually the easiest way to do that is to put the
> > version in the search query.
> > 
> > Are our users incapable of finding the right version of a document
> > if we clearly mark the version to which each document applies? Every
> > URL now has a release series name or version tag in the path. The
> > docs theme inserts the version number into every page as well. Is
> > that sufficient to help a reader understand what version the info
> > they're view is for?
> > 
> > That's not to say we shouldn't do some work to make newer docs easy
> > to find. If we can modify the sitemap to make them appear earlier
> > in search results, that's good. The docs theme allows a project to
> > include links to several older versions to switch between them,
> > too, so users who land on the "wrong" version can switch. We could
> > update that to include branches as well as tags, so that someone
> > can easily move to the series they need without knowing the version
> > number.
> [...]
> 
> The biggest liability is people not realizing there are multiple
> "versions" of OpenStack finding an old install doc and using it
> because they don't know it's out of date, then seeking support
> upstream or just generally contributing to the number of deployments
> unnecessarily stuck on obsolete software. The current solution of
> not publishing installation guides for EOL releases seems like a
> good enough compromise there to me.

That content will now live in the project trees. Perhaps part of marking
branches in those repos EOL needs to include deleting the install tree
from the docs? Now that the docs are in a standard location, that could
be part of an EOL script (although it means 2 phases, since we have to
land the patch and let the docs rebuild before we remove the branch).

We could also update the openstack-manuals tree to not publish links
to the install guides (either removing the page or replacing it
with a placeholder that explains they should be trying to use a
newer version).

Doug