Open Stack

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.

Summary:
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
fix this?"

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[0] 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[1],[2] 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:

* The branches are gone so there's no way to "update" these eol docs,
  patch them to build, or maintain them going forward for those eol
  releases.

  * Should the eol docs be pulled out and put into their own separate
    github repo, where they _can_ be patched and maintained so they
    continue to be buildable and usable by those with the correct
    tools and environment?

  * There's been talk about pulling the docs into a community-
    maintained 'wiki', for ongoing maintenance, but that opens more
    questions too (who should host it? who 'owns' it? who gets write
    vs. read access? etc.)

* 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
  	  archived/eol docs.

* 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.

* 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
  those docs.

   * On IRC, we talked about adding meta keywords to the docs
     pages, as well as using the sitemap "priority" tag[3] to try
     to weight the correct pages so they're relevant to the specific
     search.

   * 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.

   * 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
     docs.o.o pages.

There is an OpenStack Operators meetup happening in Mexico City on
August 9th[4], 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[5] a month later in Denver.

Let's discuss!


[0]
https://specs.openstack.org/openstack/docs-specs/specs/pike/archiving.html
[1] https://review.openstack.org/#/c/472275
[2] https://review.openstack.org/#/c/426047
[3] https://www.sitemaps.org/protocol.html#xmlTagDefinitions
[4]
https://www.eventbrite.com/e/mexico-city-openstack-operators-meetup-tickets-34989052197
[5] https://www.openstack.org/ptg/