Open Stack

The audience for this discussion should include a lot of people who are
not on this mailing list. I'm going to reply in more detail and move it
to openstack-dev. I will refer back to this part of the thread, but
please let's have most of the conversation over there.

Doug

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