Hey docs team — I need a volunteer to drive the removal of old docs

See Issue #183: Decision time: drop old docs? - docs-fp-o - Pagure.io for background. In short, there are a bunch of very old documents which consistently come up higher than current documentation in search results. We should look at making new-documents those results better as its own project, but right now, it’s kind of a “stop the bleeding” situation. The problem is: no one seems to have time to drive this forward. I don’t think it’s hard, there’s some light document processing plus a bunch of infra requests to make. (See steps in the linked ticket.)

Would someone like to volunteer to drive this? You don’t need to do the actual sysadmin work, just help coordinate and make sure that the problem doesn’t sit there for another year. Thanks!

Assuming there is no urgent deadline, I’m willing to whittle at this for a while.

I guess I’ll start by trying to get the preview site working on my PC.

3 Likes

Honestly basically any movement is better than the status quo. So thanks!

1 Like

I would like to share some thoughts about “old docs” – there are several kind of those.

A first group is the pre-Antora era. That includes the release notes and the old documentation. This has been decided about in #118 and the work has begun (at least that’s how I understood it).

If we pursue the idea of keeping the history of Fedora and the motivations for various developments reconstructible (and therefore not simply destroy old material), we should explicitly start a “The History of Fedora” page for that purpose. We can begin with a simple list of links to the migrated release notes, and then gradually expand that with explanatory text and links to other informative sources. But we can immediately exclude all the old pages from indexing by search engines.

A second group is old docs on external sites. An example is the cloud docs. It’s on readthedocs, last update 2015 or 2016, sources are on one member’s (or former member?) private site. It’s design is like the old documentation.
I think it would be something for Matthew to contact the appropriate teams and make those sites publicly inaccessible.

A third group is outdated documentation on the current Antora docs site. Pages are of different age and lack any indicator of how current and accurate they are. At least, each page should be tagged with information about the date of creation and the date of the last update. We do something like this in the Fedora Server documentation (not terribly pretty, but we couldn’t find a better way).
I suppose this can be automated by script.
Another idea (by nirik) is to let the page grey out over the years as it is unmodified. I thought that was pretty adventurous at first, but may not be so bad after all.
The biggest problem are the Installation- and the Administration Guide. There are ways to improve the current situation with with limited effort, but that would certainly be a new thread of its own.

1 Like

Thanks Peter. It looks like Ryan Lerch has started working on the first group. So I’ll step back and let him take over. :slightly_smiling_face:

Greg, wait, don’t run away. :slight_smile:

If I read all the various tickets and old messages correctly, Ryan is working on the release notes from step 1. It seems to me that exactly what is going to happen with the old documentation has not yet been decided.

And there’s group 3. What do you think about that?

The Fedora Linux version is already indicated in a couple of places on the older Antora docs (screenshot with highlights below). I’m not sure that a big bold banner on all those pages is as necessary.

I do think it would be nice if the topmost item of the navigation menu showed, for example, “Fedora Linux 29 User Docs” instead of “Fedora User Docs”. I have no idea how difficult that would be though. I’ve never done work on the Docs part of the project before.

“Pirate mode” is one of my favorite features of the Trello kanban software — no piracy involved, but cards which aren’t touched slowly “age” visually as if they’re old paper (like an old pirate map). I’ve often wished we had something like that for the wiki. But maybe we can figure out how to do something similar for antora — maybe not so cute, but an automatic warning at the top of the page and instructions on how to help refresh.