Here are a few proposals I have about various improvement on the Fedora Documentation website.
Most of them are related to existing tickets opened here: Issues - fedora-docs/docs-fp-o - Pagure.io.
I am posting them here to get more audience feedback, as some related tickets are quite old and may have lost interest.
Provide a stable URL for the current Fedora Linux documentation (#16)
Our build system is able to provide us an URL for the lastest version in the following form : docs.fedoraproject.org/en-US/fedora/lastest/ instead of docs.fedoraproject.org/en-US/fedora/f35/ (we can choose any word instead of latest)
Pros:
We don’t have anything specific to do for each new release. When F36 go out, it will automatically become the latest and F35 will have its own dedicated url as before.
We don’t have to update all others websites to point to the newer release anymore.
Cons:
We loose the dedicated URL for the current release; docs.fedoraproject.org/en-US/fedora/f35/ will not exist until f36 is out.
If we decide to enable this feature, I think we should do it during the release period so it doesn’t break any existing links.
Add a banner on previous versions to inform the user a new one is available (#116)
We can automatically have a banner for anything not current.
Rawhide would have something like this:
A link to the current version can be added, if necessary.
Additionally, we could implement an is_eol attribute we can use to display an End Of Life version of this banner.
Remove versions from the left menu when not needed
As of now, the version of every component is displayed, even if there is only one.
Proposal is to remove them, unless you have more than one version available.
Let me know what you think, and if you have any suggestions for improvement not listed here.
The “we lose the dedicated URL for the current release” con is enough for me to be opposed to this proposal. If we could add latest as a symlink (or HTTP redirect or whatever implementation) and still have the canoncial URL contain the version, I’d be on board. But right now we’re trading one problem for another, and arguably worse. (For example, if someone wants to link to documentation specific to the F35 release, they couldn’t do that for six months after the release.)
Yes, let’s do this (for both pre-release and EOL).
Bikeshed: I’d say “Documentation for a newer release is available” instead of “a newer version of this documentation”. I think that says what we mean more correctly. The docs for EOL versions of Python, as an example, say “This document is for an old version of Python that is no longer supported.”
That’s fair.
And now that I’ve taken another look at Antora docs, it looks like there is a way to generate an httpd compatible redirect to achieve exactly that.
That would give us a a <version> url that redirect to latest (or the other way around, we can choose one or the other).
This redirect being generated at build time, it will automatically update to the next version once released.
I can set that up on staging to check if everything works out that way.
The staging environment has been updated with all these new features, including the latest URL redirection.
In addition to this, you’ll find in the footer the date of the latest update for each page. That was requested a few times and can help determine if the content may or may not be obsolete.
I very much welcome that. And we should seriously consider removing that for “User Documentation” as well. The text on the pages of all versions is the same, except for the version number (and the associated link).
And it gets really embarrassing with the Installation Guide and the Administrator’s Guide. When you browse through the versions, you immediately notice that the contents are largely the same. And all versions have in common that they do not match what actually happens in the individual editions. Removing the version would (unfortunately) not be a loss of information.
The version link is only useful for the release notes.
IMHO, that’s a big improvement, too! Is the technical side really bug-free yet? If I have a look at Fedora on Raspberry Pi :: Fedora Docs Staging, I have doubts whether there was a “real” content update on January 10, 2022 (still refers to armhfp, no mention of Raspi 4, etc). The version number at download is now 35, but otherwise?
And in the long run, the date should be placed in a much more visual location, perhaps as a footer of the ToC if possible?
And it would also be good to explicitly mention the Fedora version(s) that the documentation refers to and has been tested on.
It’s not.
The last update is supposed to come from the git history of the adoc file. For some reason, that’s not the case here… I’ll try to dig and find where that date comes from.
Maybe the issue is a bit more complicated. It is possible that the text in the example was actually changed on said date, e.g. by replacing the release number. Do we want to consider this already a relevant update? Should we additionally consider the share of changes in the total text. Even if that would be feasible, would that also make sense? Or do we need a (manual manageable) marker as on the wiki pages (“just a minor update”)? At least in the long run?
But regardless of these questions, we should definitely introduce the addition in the footer everywhere.
The advantages of /latest/ could be facilitated by further implementing #187. Especially google rankings will be facilitated by both (no language/locale in the link + always latest for the current release).
The likelihood of getting legacy pages of Fedora Docs is still high. I have seen such issues also on ask.fedora. People often don’t question what they get when using google (the warning on obsolete pages often makes no difference).
While I totally agree with the use of /latest/ to improve our rankings (among other things), I’m not sure to understand how removing the locale from the url would help improve it in any way.
It could merge different links to one; such as docs.fedoraproject.org/de/fedora/f35/ docs.fedoraproject.org/en-US/fedora/f35/ docs.fedoraproject.org/be/fedora/f35/
The value is obviously not as high as with /latest/. The question is how far the return on invest is acceptable, especially for automatically determining the locale of the request. If it remains with “no locale” = en_US, you are right; then it would just replace one link by another.
Speaking of search engine rankings, removing old docs could be done by explicitly disallowing indexation in robots.txt (see #166).
Should we also include rawhide documentation in that list?
This was actually a bug in the git library I used. This should be fixed now.
And a few updates on the other changes discussed so far:
latest url scheme is deployed on stg, and waiting the end of freeze for prod (PR on infra side)
Banner on old/rawhide is deployed on prod. Note that it affects all versions not current, regardless of EOL status.
Versions removed from navigation menu, also deployed on prod.
This would indeed strongly decrease the issue of ending up at obsolete pages. But I assume this would imply a reoccurring, biannually task (a very small one, but it has to be kept in mind): each time when support for a release ends, an adjustment of the file will be necessary; so, /f34 would be the next to become disallowed.
I don’t know whether maintainer/developer use search engines when working on the rawhide docs, or if they solely work with the raw files in git. Maybe we should clarify this first just to be sure?
I was actually referring to the old docs site. But we can extend that to the new one too.
Anyway, I think we should be able to generate this file at build time so we don’t have to think about it.
Yes, this is a big nuisance and exclusion from indexing may help. The sooner, the better.
Another major annoyance is wiki pages that have not been maintained for years and are orphaned.
It would be good to redirect all wiki pages whose last change is further back than 31.12.2017 to docs start page (there is a macro, I don’t have it in my head right now).
The older Antora based pages are not quite as annoying, I guess.
Let me know what you think
This is only a proof of concept, and might not be production ready. There is not much we can customize (other than the look and feel with css) and It may cause a small but noticeable performance hit.
I love it! Very intuitive. But I also have the loading issue. After the remaining page has already loaded, it takes a moment until I can use the search field (Firefox 98.0 from Fedora repo, Fedora 35). Maybe that’s just a problem of the test environment?
Awesome! Overall this is a huge improvement. (It’s infinitely better than our previous search options )
I definitely noticed the page load issue. Maybe we could have it be a link to a dedicated search page? The downside is adding an additional click, but it would reduce the impact of the page load times.
One thing that might improve the experience, if we have any way to change it, is to include the breadcrumb in the search results listing. The page titles are not always helpful in providing context. If we can’t change that, we should try to make sure page titles are more contextual going forward (that’s a problem to fix over time, not an immediate issue)
)