Open Stack

On Wed, Jul 26, 2017 at 8:49 AM, Jeremy Stanley <fungi at yuggoth.org> wrote:

> The goal there was to prevent people from submitting
> errata for end-of-life documents to reduce overall review workload
> and to be able to signal to people that they shouldn't bother trying
> to fix those outdated versions but rather get any necessary fixes
> into the latest versions of the document instead.
>

I definitely agree with the goal, but there's a series of "final, closure"
changes that need to be made to the tree before it's tagged and retired,
and that is to point all of the various resources to their tag name
counterpart (?h=stable/liberty => ?h=liberty-eol).

If this step isn't done, the doc tree needs to be patched with changes in
order to build correctly with Maven and/or Tox. It's a minor nit, but right
now every $release-eol tagged release needs to be patched in this way to
build correctly, as well as some other fixes to address incorrect xrefs and
links pointing to upstream 404 resources.

There's also many operators who run these releases well beyond their
upstream EOL dates, and may need to enrich or update the docs in a way that
facilitiates that runtime/operational capacity. Not necessarily "fixes" in
the context of bugs, but enhancing the clarity or quality of the docs
(adding additional examples is one I can think of)

Updating to the latest versions of the docs is always preferred, except in
cases where the components have changed or been deprecated within newer
releases (nova-network => neutron, etc.). I think this is where the idea of
maintaining these errata in a wiki probably started (which predates my
involvement).


> I don't see where this solves anything. If there aren't available
> maintainers for those versions of the documentation when it's in the
> original repos, how would moving them into another repo change that
> at all?


The only reason to suggest that, would be to support those post-retirement
fixes that permit them to build correctly. If those changes were made _at
the point where the release is tagged and retired_ in the main repo, then
that idea wouldn't be necessary... unless the docs moved locations, and
those references broke (docs.o.o => archives.docs.o.o for example).


> This just comes back to the same discussion we have
> repeatedly about stable branch maintenance in general, supporting
> more releases for longer, LTS releases and skip-upgrading, et
> cetera. The resources to help maintain these sorts of things need to
> show up first and prove that they're involved on the team before we
> can, as a community, safely promise to extend/increase support
> durations.
>

We definitely all feel your pain, and we're all under thin resources and
tight deadlines. I don't think we're suggesting that the release branch
itself be maintained beyond its eol date, just that when those releases are
retired, the documentation that goes with those releases vanishes, although
many sites are still running those releases for months to years beyond
those dates, and that presents a problem.

Also, one other possible solution which I haven't seen suggested
> yet: why aren't distros packaging copies of the documentation just
> as they package other built software? Much like packaging our
> software so versions past EOL upstream can continue to be
> consistently installed, the same goes for availability of
> documentation contemporary with it.
>

Having documentation locally in the same context as the server/cluster
itself is one thing, but having the documentation made available on the
same site/location as the rest of the documentation for all of the other
releases is just-as-or-more valuable, as well as having the docs visible
and available from other hosts, mobile devices, tablets held by ops team in
the DC, etc.

If you install docs for your liberty install today, and want to review docs
for mitaka or any other release, now you have to work out the deps, or
upgrade your cluster, or any number of machinations and install those docs
packages "somewhere" so you can read/review them. That also doesn't
guarantee that it's going to be web-accessible, searchable, indexed and so
on.

This also means that each OS distribution needs to build, maintain and
deploy their own version of those docs via packages, so one set of docs
packaged for Canonical, one set for RHEL, one set for Oracle and others.
I'm much more inclined to address them at the upstream source, than
propagate them south and maintain them separately in multiple places.

It's an interesting idea, but there's overhead and complexities associated
with this approach, as well as the other ideas I've suggested. Nothing is
free, unfortunately. We (all) have to weigh the benefits and resources
needed to make that work for our respective communities.

I'm just one voice of many, so feel free to tell me I'm full of sod and
let's work through what we can all agree is the best, strategic solution
going forward.

Thanks for your comments, you've given me some ideas to think about!
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20170726/c020f55b/attachment.html>