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

Jeremy Stanley fungi at yuggoth.org
Thu Jul 27 22:07:33 UTC 2017

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.
Jeremy Stanley
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 949 bytes
Desc: Digital signature
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20170727/ebacd8c8/attachment.sig>

More information about the OpenStack-dev mailing list