#118 [Pre-antora documentation] Add banner to documentation for EOL releases marking it as outdated
Opened 2 years ago by ankursinha. Modified 6 months ago

Following up form #116.

We need to modify the HTMLs for pre-antora documentation to add this banner.


  • where are the HTML files? (can one open PRs)
  • what should the banner say?

  • can this be scripted? (hopefully!)

We got an informative bug report in BZ about this: https://bugzilla.redhat.com/show_bug.cgi?id=1435506

The reporter provided some suggestions about how to fix this:

Pages must identify their language [1] and give rel="alternate" links to the page in other languages [2]. Pages should also use a canonical URL to identify the "master" version of the documentation (Fedora 25 right now) [3], so the Fedora 16 documentation of some feature gets lower search ranking than the documentation for the current Fedora version. I think you could also put language information for the canonical (most recent Fedora version) URLs into a sitemap on docs.fedoraproject.org [4] instead of updating all these old pages. As far as I can tell, docs.fedoraproject.org pages do none of these, hence it's hit or miss what Google returns.

[1] https://www.w3.org/International/questions/qa-html-language-declarations
[2] https://support.google.com/webmasters/answer/189077?hl=en
[3] https://support.google.com/webmasters/answer/139066?hl=en
[4] https://support.google.com/webmasters/answer/2620865?hl=en&ref_topic=2370587

The old docs aren't even in the sitemap since Antora doesn't know about them, they're just linked from the frontpage. Actually they probably have their own, which is likely part of the problem, and we might need to fix that.

We might be able to modify each HTML file's headers while adding in the warning banner directing people to docs.fp.o too, and add the language and identify the canonical English version.

Oh, one more thing, the report also makes a suggestion to just drop old publican docs, since the Internet Archive has snapshots of them, so if anyone really wants to see docs for a very outdated version like that, they could go there. That seems worth a consideration.

Please just NUKE the old Fedora docs. Today I searched for temporarily disable Fedora firewall Fedora 31 and the first result from a Fedora site is 3.8.9. Disabling firewalld - Fedora Documentation... from Fedora 19. (First I just searched for my problem, got this obsolete result, then added "Fedora 31" and it still didn't help!)

The existence of old yet highly-ranked Fedora docs makes searching for Fedora help a miserable experience for anyone who doesn't do it every week. Adding an "End of Life" banner won't help unless it appears in search results snippets. Instead please kill these old releases with fire. They're all EOL, it's crufty deadweight slowing you down. Something like cd WWWROOT/Fedora; rm -rf {7,8,9,1?,2?}/ Thank you!

The old docs aren't even in the sitemap since Antora doesn't know about them, they're just linked from the frontpage.
the Internet Archive has snapshots of them

The front page's "Older Releases | Older Fedora user documentation" can link to, e.g. https://web.archive.org/web/20181026184447if_/https://docs.fedoraproject.org/en-US/Fedora/26/html/Release_Notes/index.html , that seems to be a relatively complete crawl of the site. Or maybe the old toc.html sitemap at the Internet Archive...

Actually they probably have their own [sitemap], which is likely part of the problem, and we might need to fix that.

At the bottom of the lovely left-hand navigation for all these obsolete releases is a (Map) button which goes to https://docs.fedoraproject.org/toc.html which seems multi-lingual and useful but it only lists obsolete releases. Kill that page too.

Still a problem: https://ask.fedoraproject.org/t/when-doing-internet-search-old-docs-are-top-hit-for-me/13995/

What can we do to move this along? If we can break the plan down into individual tasks, we can try to find folks to do them?

PS: sorry for the inactivity here for such a long time. Slipped my radar, and then got buried in the backlog :(

I recently re-suggested the banner idea, but on re-reading this, I think we should just drop it all.

Let's close this in favor of my concrete suggestion in https://pagure.io/fedora-docs/docs-fp-o/issue/183.

Login to comment on this ticket.