Open Stack

Excerpts from Doug Hellmann's message of 2017-07-27 19:05:16 -0400:
> 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
> 

Today we're publishing series-specific (e.g., newton) and
version-specific (e.g., 10.0.0) docs. I wonder if we should stop
publishing docs when we tag repositories, and just stick to the
series? There's no way to go back and update those version-specific
builds after the fact, so we can't remove the installation guides
and we can't rebuild them easily if there are security issues with
the content.

Doug