Open Stack

[Moving a thread from the openstack-docs list [1] to this list for
broader input.]

[1] http://lists.openstack.org/pipermail/openstack-docs/2017-July/010069.html

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?"

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

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

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

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

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:

1. We cannot build content for which branches have been deleted,
   so we can't fix issues .

2. We may not have space to host content forever.

3. 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
is today?

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

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.

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

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

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.

Doug

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