<div dir="ltr">On Wed, Jul 26, 2017 at 8:49 AM, Jeremy Stanley <span dir="ltr"><<a href="mailto:fungi@yuggoth.org" target="_blank">fungi@yuggoth.org</a>></span> wrote:<br><div class="gmail_extra"><div class="gmail_quote"><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">The goal there was to prevent people from submitting<br>
errata for end-of-life documents to reduce overall review workload<br>
and to be able to signal to people that they shouldn't bother trying<br>
to fix those outdated versions but rather get any necessary fixes<br>
into the latest versions of the document instead.<br></blockquote><div><br></div><div>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). <br><br>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.<br><br>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)<br><br></div><div>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). <br></div><div> <span class=""></span><br><span class=""></span></div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><span class=""></span>I don't see where this solves anything. If there aren't available<br>
maintainers for those versions of the documentation when it's in the<br>
original repos, how would moving them into another repo change that<br>
at all?</blockquote><div><br></div><div>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). <br> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"> This just comes back to the same discussion we have<br>
repeatedly about stable branch maintenance in general, supporting<br>
more releases for longer, LTS releases and skip-upgrading, et<br>
cetera. The resources to help maintain these sorts of things need to<br>
show up first and prove that they're involved on the team before we<br>
can, as a community, safely promise to extend/increase support<br>
durations.<br></blockquote><div><br></div><div>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. <br><br></div><div></div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">

Also, one other possible solution which I haven't seen suggested<br>
yet: why aren't distros packaging copies of the documentation just<br>
as they package other built software? Much like packaging our<br>
software so versions past EOL upstream can continue to be<br>
consistently installed, the same goes for availability of<br>
documentation contemporary with it.<br></blockquote><div><br></div><div>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. <br><br></div><div>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. <br><br></div><div>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.<br></div><div><br></div><div>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. <br><br></div><div>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.<br><br></div><div>Thanks for your comments, you've given me some ideas to think about!<br></div><div><br></div></div></div></div>