Linking to removed versions of documentation

[Zoran Regvart <zo...@regvart.com>]

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?

zoran
-- 
Zoran Regvart

Re: Linking to removed versions of documentation

[Zoran Regvart <zo...@regvart.com>]

Hi David,

On Sat, Nov 13, 2021 at 2:41 PM David Jencks <da...@gmail.com> wrote:
> >> 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.

Oh, that's really neat I like that

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

In the Gulp build of the UI we use gulp-rev so file gulp-rev so that
CSS and JavaScript files have a hash in them, e.g. site.css becomes
site-9775b2354a.css, this in turn allows us to set caching (for 1 year
IIRC), but still push out new versions and get the browsers to update
and use the latest version as the hash part changes. This gives us
better performance and saves some bandwidth for ASF and end users.
When we publish we delete everything and copy over the latest version,
so if a CSS file is updated and it now has a different filename, the
old CSS file will be removed and a new one published.

So if we're to keep old versions of HTML files there is a good chance
that they'll point to an older CSS file, so if we remove it we'll
break the formatting.

We'll just need to take that into consideration if we're going to keep
old versions around to keep the old resources that they use around as
well.

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

Yeah, or we put a placeholder page if there is no new content to point
to, that explains that the content was removed as it's no longer
relevant.

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

I was thinking either have them point to the website, with some magic
needed here to publish with absolute links to other subprojects; or
expect that the subproject's documentation is extracted in the same
directory so the links are still valid.

I feel like we need to decide if we're going to take on all this work,
i.e. do we care about making older versions of the documentation
available? Seems like quite a lot of work, so if we're not certain
that there is a need for this, perhaps we should not be doing it...

zoran
-- 
Zoran Regvart

Re: Linking to removed versions of documentation

[David Jencks <da...@gmail.com>]

> 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.jencks@gmail.com <ma...@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

Re: Linking to removed versions of documentation

[Zoran Regvart <zo...@regvart.com>]

On Fri, Nov 12, 2021 at 8:55 PM David Jencks <da...@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?

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.

What would happen when an older version of the docs points to a page
in the user manual that we removed/renamed?

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

zoran
-- 
Zoran Regvart

Re: Linking to removed versions of documentation

[David Jencks <da...@gmail.com>]

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

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.

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.

David Jencks