#116 [Antora documentation] FInd a way to easily mark documentation for EOL releases as outdated.
Opened 2 years ago by ankursinha. Modified 2 years ago

We've now had multiple cases of users looking for information reaching documentation for EOL releases. These are mostly from search engines.

While those in the community will know that information for previous releases, especially EOL ones, does not apply to current Fedora releases, this is not apparent to end-users.

What can we do to make this clearer?

  • remove docs for EOL releases maybe (replace it with: this release is EOL, please refer to current documentation -> link to current doc)
  • if that is too drastic, a big banner on every page saying that this is outdated documentation maybe?

Here's an example of a user trying out instructions from Fedora 12 that they found using a search engine on a Fedora 29/30 installation:


EDIT: For pre-antora documentation, please refer to #118.

It'd be nice to see these docs get a banner, ideally with a new link to click to the latest docs. The banner is a good MVP. We also need to get a banner on to the really really old docs ...

I hope this can be scripted, even given that our old docs followed different formats/tech :pray:

Should this be added as part of the docs team's release cycle related tasks----"mark EOL docs as such"?

This is a good point. Having a banner there would make sense. Help with implementing this is more than welcome!

Would you know where someone interested in this should start? Lots of questions: :smile:

How are the EOL pages to be modified? Didn't they use publican back in the day, for example? Will one have to modify the source and re-generate them, or does one simply add to the HTML---if so, where are the HTML sources?

It's probably better to modify the sources, not generated HTML.

How about this: A while ago someone on the docs list proposed creating a "shared partials" repo: https://lists.fedoraproject.org/archives/list/docs@lists.fedoraproject.org/message/OUDAIOBDKTMQOSMHAPLDIYVD2KXZC4JK/. I still didn't get around to it, but when I make it, we could store the banner there - just a simple file with a [NOTE] saying this documentation is outdated and pointing to the docs front page where people can find up to date docs.

Then we could write a script that inserts an include pointing to the banner into every page in each module on branches for EOL releases.

I can see a few issues with this, though:

  • The banner would show up on top of each page, so if any user lands on an anchor in the middle of a longer page, they won't necessarily see it.

  • I'm not sure off the top of my head, but I think some of our docs have pages composed of multiple source files. Doing this would make the banner show up in multiple places on a single page, which would look weird. We could go through each doc and make sure that either one page = one source file, or that any sources that aren't top-level pages are in _partials, but that's a lot of extra work.

Now that I wrote all that I thought of a second approach. @asamalik do you know if it's possible to set the UI bundle (or layout) per repo/branch instead of setting it for the whole site? We could make another bundle (or another layout in the default bundle) that has a huge floating banner on top - is that possible?

Building on this, for pre-Antora docs, I encourage us to modify the HTML directly as we are unlikely to be able to easily regenerate those pages from source again.

Yes, that's true, we don't have any other choice than to modify the output for pre-Antora docs.

Yes, that's true, we don't have any other choice than to modify the output for pre-Antora docs.

Created #118 specifically for pre-antora docs, and editing the title here to make it specific to antora docs from now on.

Login to comment on this ticket.