Open Stack

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

I've proposed https://review.openstack.org/489231 to update
project-config to stop publishing docs when we tag releases.

Doug