[openstack-dev] [docs][release][stable][ptl][infra] Strategic discussion regarding the future of documentation for EOL releases

Doug Hellmann doug at doughellmann.com
Thu Jul 27 23:10:32 UTC 2017

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.


More information about the OpenStack-dev mailing list