search

oilshell / oil

Oils is our upgrade path from bash to a better language and runtime. It's also for Python and JavaScript users who avoid shell!
http://www.oilshell.org/
Other
2.78k stars 150 forks source link

'view latest' released version in documentation - because old links are often surfaced #2000

Open dezren39 opened 1 week ago

dezren39 commented 1 week ago

hi, i've gone through a lot of your documentation, and appreciate your heavy linking. i propose adding a 'view latest' url on all documentation pages immediately before "all versions" which links to this exact page but in the latest documentation. if it is already the latest either its a link to itself or it says "latest version!" or links to view previous. right now i know to click 'source' and i can read straight off github master branch, but a user might just think 'this is 0.18 and i'm on 0.22' and updating one url is fine, but if you opened... a dozen or two pages... it would be tedious to update the url and they may not want master depending on what changes you have in there.

more difficult and less immediately valuable: it could be nice if one could pull up the disambiguation page for all versions of the current page. one way that i thought of is if you end up on releases page from documentation, it stored the page name in the url, and a link on each release appears. but that sounds hard, probably easier to auto-generate a versions page for each article that looks a lot like the releases page but not, could show all versions that have it. there is some complexity here where you'll end up like wikipedia and you may end up needing to 'move' pages to a deprecated page goes 'to' somewhere and some new pages are 'from' some old one etc.

it also might be nice to allow some kind of 'perma' link using 'latest' instead of a specific version number in the url. but if you do i ask please never delete a page, link to the last version the page existed with a big warning banner or something or just continue with the specific url versions you have. deadlinks make me sad. :(

i appreciate the mountains of texts to read through and hope to ensure its easy to direct link without to without needing archive.org and without fear of deadlinks or deprecation.

andychu commented 1 week ago

OK yeah I think we need to do something here, because the search engines do tend to link to old docs

Thanks for reading!