[Moving a thread from the openstack-docs list  to this list for
Excerpts from 's message of 2017-07-26 07:42:38 -0400:
Yesterday was a very busy day on IRC, with the discussion about the
strategy and future maintenance of the documentation for the EOL
releases coming back to the front.
I've promised to summarize some of what we discussed, for those who
weren't there, and sketch out some of the fenceposts along our path forward.
The main issue, is that when an OpenStack release goes EOL, the branch
in the main repository goes away, and with it go the docs, which then
vanish from the public-facing website.
This has been an open gap for awhile, but only recently became a pain
point for many operators. I think we can all agree that this is an
issue, so the "Why should we fix this?" isn't as important as "HOW do we
Yes, as I said on IRC, I think we have reached a point where enough of
our user base is trailing far enough behind that we need to rethink our
documentation retention policy to make sure we're meeting everyone's
This leaves any sites, operators or installations that may be using
those releases, without any tangible way to research how to install,
manage or maintain those in-place installations and releases.
For companies like Canonical, we support OpenStack on Ubuntu LTS
releases beyond the upstream EOL date of those point releases
themselves. Other distributions may have a similar gap with the docs
vanishing before their support of those releases sunsets.
Ideally, docs should be managed and maintained at the upstream project
site, not at each disribution's own domain. I'd like to avoid having a
Canonical version, a Red Hat version, an Oracle version, etc. all with
the same patches to build local copies staged on our respective domains.
I've recently put some effort into automating and patching off the older
versions of the docs based on the github tags, so they build in a local
tree with mvn/tox, and that tree can be used internally by operators,
but this should be viewed as a stopgap to a more strategic archiving
solution for these docs.
There is an archiving plan that has been discussed, but with the -doc
team resources being thinned out, there is very little "spare" resources
to put towards this effort. There's been some discussion, to try
to bring this to the front, but it too suffers from time and resources.
There are a few key problems/challenges/questions with solving this in a
repeatable, strategic way:
As Jeremy pointed out on the docs list, this doesn't really help. Moving
the content won't give us more maintainers. I don't think we want to
enable "maintenance" of the docs as such, though. I think we just want
to make them available as they are for users to find. This week we made
some progress there, so that now docs.openstack.org has a landing page
for every series (for example https://docs.openstack.org/austin/).
For the series where docs still existed on the server, we added
links. The earliest release with any docs available was Icehouse.
We have progressively more material as you look at more recent
Where should the docs ultimately "live", until they're truly eol for
all parties concerned, and what should that timeline be? 3 years
past eol? 5 years? Indefinitely?
- We discussed something like: docs.o.o/eol_$release or similar
indicator to differentiate the 'current' docs from the
Should the docs for eol releases be made available in PDF only
format, or indexable/searchable HTML format? There are pros and
cons for using either approach, this might need more thought.
I think we want to take a "less is more" approach here. When we had
lots of contributors working on the docs, it made sense to ask them
to do things that I think we can't afford to do any more. So rather
than looking for a new way to do something, let's see if we can
stop doing work and achieve more.
My proposal is to put the documentation on docs.openstack.org and
leave it there indefinitely.
Leaving the docs where they are avoids a ton of work to build
archiving systems and fix broken links in the future, which gives
the docs team more time to create and improve future content. It
also avoids having to remove the docs when a release goes EOL, which
is another manual process today.
We had a few different reasons given for the current retention
policy that would need to be addressed by any change, much less one like
keep everything forever:
We cannot build content for which branches have been deleted,
so we can't fix issues .
We may not have space to host content forever.
Readers will file bugs against old documentation.
For point 1, we need to be clear that we're not talking about
supporting adding or enhancing any content to old docs, or even
fixing errors. After a branch goes EOL, the docs are as complete
as they are going to be. The only reason we should worry about
building them again is to address security issues with the JS or
CSS or whatever else is in the built docs (which is a real problem
we had a year or two ago).
If we cannot resurrect the branch to update it and rebuild the
content, and cannot replace the JS or CSS file through a process
other than a full doc build, then it seems reasonable to delete the
content. I have a lot of hope that our current doc toolchain will
make it easier to resurrect and rebuild older branches, because all
of the dependencies for building the HTML can be installed via pip.
It will still require some additional work, but I don't think it's
as hard as it has been in the past.
Regarding point 2, if we don't have the space to host the content
indefinitely, then we need to set a fixed, but longer, retention
period before deleting it. Several years, at least. In the mean
time, we could delete builds for intermediate versions (maybe if
we have 10.0.0, 10.1.0, and 10.1.1 we only need to keep 10.1.1, for
example). The point is that there are ways to remove some content
without removing it all. I know space used to be a real problem
when we were hosting on CloudSites, but maybe someone from the infra
team can give us some insight into how significant the space issue
And regarding point 3, it seems like we could close the bugs WONTFIX.
I don't know how often that issue comes up, though, so maybe someone
on the docs team with more info can give us an idea how much work that
is likely to be.
Did I miss anything in that list?
How does the -doc team ensure that public searches for the correct
version of the docs comes up first in the SERPs (Search Results
Pages), so someone seeking information on Ocata, doesn't land on
Liberty(eol) docs and incorrectly alter their environment based on
On IRC, we talked about adding meta keywords to the docs
pages, as well as using the sitemap "priority" tag to try
to weight the correct pages so they're relevant to the specific
Another solution is to not add the eol docs to the main sitemap
on docs.o.o, and let the search engines find them on their own,
lowering the chances that someone accidentally trips on the wrong
version of the docs. The recent watermarking of the release name
is a good visual indicator, but I think we can do a little better
for our respective user/customer communities.
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
- One other possible option is to have a completely separate TLD
for the eol release docs (archive.o.o?), with its own sitemap
that search engines are indexing independent of the main
Moving the content to a different top level domain would break a lot of
the links. Moving it and fixing the links would require even more work.
I would prefer to invest our limited resources on new content.
There is an OpenStack Operators meetup happening in Mexico City on
August 9th, and this specific topic has been pulled into its own
dedicated session there. I'm hopeful that any positive (or negative)
feedback and notes from that session can make their way back to this
list, and further into the PTG a month later in Denver.
Please encourage everyone there to explore options that require the
least amount of effort. An ideal solution is one we can implement
without heroic efforts or having to recruit an army of contributors.
OpenStack Development Mailing List (not for usage questions)