Dealing with legacy documentation, `release-notes` especially #809

New issue

Open

opened 2025-04-26 20:19:11 +00:00 by helle · 4 comments

helle commented

2025-04-26 20:19:11 +00:00

Member

in the documentation we include historical release notes and these may reference bits of documentation that do not exist anymore

in the process of making a link checker that actually can deal with how our manual is built and give usable outputs of what files potentially are at fault, we have been running the work in progress version against the current Lix documentation and while most errors are easy enough to fix, we are not entirely sure what the right approach is for the release-notes

currently, the only known example is that rl-2.18.md references #xp-feature-discard-references which well, due to the release itself, no longer exists

should we remove these links to avoid the appearance of floating links, or do we instruct the link checker to not check such legacy documents and just let them be

our proposal

we propose simply removing the links and turning them into just a simple mentioned reference in the text, despite that this changes the historical release note, this provides a cleaner result and means we have zero links with missing references

it also fits the fact that the current text of the manual indeed does not have this option anymore and hence any references to it are pointless

## in the documentation we include historical release notes and these may reference bits of documentation that do not exist anymore in the process of making a link checker that actually can deal with how our manual is built and give usable outputs of what files potentially are at fault, we have been running the work in progress version against the current Lix documentation and while most errors are easy enough to fix, we are not entirely sure what the right approach is for the `release-notes` currently, the only known example is that [rl-2.18.md](https://docs.lix.systems/manual/lix/stable/release-notes/rl-2.18.html) references `#xp-feature-discard-references` which well, due to the release itself, no longer exists should we remove these links to avoid the appearance of floating links, or do we instruct the link checker to not check such legacy documents and just let them be ## our proposal we propose simply removing the links and turning them into just a simple mentioned reference in the text, despite that this changes the historical release note, this provides a cleaner result and means we have zero links with missing references it also fits the fact that the current text of the manual indeed does not have this option anymore and hence any references to it are pointless

helle added the

docs

label

2025-04-26 20:19:11 +00:00

jade commented

2025-04-26 20:40:44 +00:00

Owner

I think that the only other viable option to this is linking to the previous manual where it was present but this doesn't make any sense since the job of the manual is documenting what currently exists. Removing the links appears to be the best course of action to me.

pennae commented

2025-04-26 21:34:29 +00:00

Owner

agreed, turning the links into plain text is probably the best option. old versions of the manual can still be inspected to find those references if needed. in the future we may want to keep a log of experimental features and their stabilization/removal/etc as an appendix though?

helle commented

2025-04-27 10:33:22 +00:00

Author

Member

solution

for this one I will remove it and turn it into a textual reference to the former experimental feature, it makes sense as it predates lix, so adding to a maturation/removal log makes no sense

will be submitting a patch soonish with the other more obvious link fixes, but that will include this one as well

further discussing handling this in the future

and yes, we would say such a log is useful, one of the issues with lix/nix is if you find documentation online, even semi-recent stuff, determining the relevance and correctness of it can be tricky, if it suggests a experimental feature that doesn't work anymore (either due to maturation or removal) going through all the relnotes is not the shortest thing (search is not a panacea)

and we can update historical relnotes to refer to this log if need be, so they aren't pointing to the void and it is clear what happened to the feature without changing the nature of the notes

meta

though we are curious what this feature actually meant in terms of changes/abilities and are surprised it has no remaining indication of it's existence in the manual despite being stabilised (we presume, because the documentation of such attributes is just NOT in our current docs, this is a whole other kettle of fish, we are aware)

## solution for this one I will remove it and turn it into a textual reference to the former experimental feature, it makes sense as it predates lix, so adding to a maturation/removal log makes no sense will be submitting a patch soonish with the other more obvious link fixes, but that will include this one as well ## further discussing handling this in the future and yes, we would say such a log is useful, one of the issues with lix/nix is if you find documentation online, even semi-recent stuff, determining the relevance and correctness of it can be tricky, if it suggests a experimental feature that doesn't work anymore (either due to maturation or removal) going through all the relnotes is not the shortest thing (search is not a panacea) and we can update historical relnotes to refer to this log if need be, so they aren't pointing to the void and it is clear what happened to the feature without changing the nature of the notes ## meta though we are curious what this feature actually meant in terms of changes/abilities and are surprised it has no remaining indication of it's existence in the manual despite being stabilised (we presume, because the documentation of such attributes is just NOT in our current docs, this is a whole other kettle of fish, we are aware)

lix-bot commented

2025-05-01 11:30:15 +00:00

Member

This issue was mentioned on Gerrit on the following CLs:

commit message in cl/3076 ("Fix various links to anchors in documentation.")

This issue was mentioned on Gerrit on the following CLs: * commit message in [cl/3076](https://gerrit.lix.systems/c/lix/+/3076) ("Fix various links to anchors in documentation.")