> On Nov 13, 2021, at 1:31 AM, Zoran Regvart <zo...@regvart.com> wrote: > > On Fri, Nov 12, 2021 at 8:55 PM David Jencks <david.a.jen...@gmail.com > <mailto:david.a.jen...@gmail.com>> wrote: >> >> >> >>> On Nov 12, 2021, at 11:20 AM, Zoran Regvart <zo...@regvart.com> wrote: >>> >>> Hi Cameleers, >>> Our current practice is that over time we would remove older versions >>> of documentation, we do this usually after a release of the new >>> version. We keep the LTS versions but we remove the older visions. >>> Sometimes we do this vigilantly, sometimes it takes a while till we >>> notice that an older version is still being published. >>> >>> Overall we do this for one primary reason, the build performance is >>> directly tied to the number of Antora components/branches being built. >>> If the build took a constant amount of time, regardless of the number >>> of components/branches being built we would probably leave more older >>> versions around. There is also some maintenance to keeping older >>> versions in case where we make a change on the website that is not >>> backward compatible and it breaks the older version -- but I don't >>> think we have had this issue thus far. >>> >>> This has recently been discussed (on Zulip or a GitHub issue, I can't >>> seem to find), a Camel user was asking about older versions of the >>> documentation; and again in the last few days the build was failing as >>> we pointed to an older version of the documentation from one of the >>> blog posts. >>> >>> I think we should discuss how we handle this, and explain our policy >>> somewhere on the website. >>> >>> What do you think, should we keep doing as we have been doing and >>> remove older versions? Should we keep all/more versions around? Can >>> someone think of a way we could keep the older versions around and not >>> jeopardize the build performance? >> >> There might be a way to keep older versions around without building them. >> Dan Allen came up with what he calls a “site manifest” which is a json file >> with all the pages in a site listed with enough info that xrefs to them can >> be computed. His original motivation was a “sharded site” which I think >> means there’s a big main site and then a supplemental site, not referenced >> from the main site, but with links to the main site. The site manifest from >> the main site lets xrefs from the subsidiary site to the main site be >> resolved. >> >> I’ve turned this into an Antora extension (with some modifications) and have >> been using it to have quick partial builds of the camel site, something I >> intend to talk about soon. > > Oh, that sounds really interesting. > >> I think we can use it sort of in reverse to publish a site manifest for each >> obsolete component version and use it to add to the component explorer. It >> will take some thinking and a bit of work but should not be too hard. > > Hmm I need to wrap my head around this, sounds like we would build the > version against the site manifest and never build it again? How's that > different from building it, keeping the HTML files around and then > removing that version from the playbook?
With this plan we’d keep the HTML files around: the difference is that Antora would know about the old pages, so links to them would work and the versions would show up in the component explorer. > > We use hash of the CSS files for cache busting, so we'd need to keep > the older version of CSS files as well. Not really an issue, just > something we need to accomodate for. I don’t understand how this works. I would expect that everything Antora related would use the same UI and if we changed the html generation enough (maybe Antora 4 or if we added a custom template) we’d do a one-time regeneration of all the old docs. > > What would happen when an older version of the docs points to a page > in the user manual that we removed/renamed? Well, we shouldn’t be doing that now without leaving behind a redirect, hopefully soon via a page-aliases attribute :-) > >> I’d suggest that we do something to make it plain on each such page that the >> page is obsolete, and in the component explorer that the version is >> obsolete. This might involve a “final build” of the component version after >> a “retirement update”. Maybe we could have an “obsolete” watermark in the >> layout and set the “obsolete” layout in the antora.yml component descriptor. > > Yeah, I've seen banners displayed on older documentation pages > prompting users to use the latest documentation/version, that would be > helpful. > > I was also thinking about having a documentation ZIP distributed with > the release downloads. Probably using a different Antora UI, perhaps a > bit lighter and without the same menus as the published website. That could be interesting too. The site-manifest idea could be used to create working links to the actual user manual. How would you deal with links to the relevant obsolete versions of other subprojects? David Jencks
