docs.rs icon indicating copy to clipboard operation
docs.rs copied to clipboard

Improve behavior after publishing a new version causes `/latest/` to lose children

Open kpreid opened this issue 1 year ago • 2 comments

Current behavior:

  1. Alice visits https://docs.rs/example/latest/example/really_useful_module/index.html.
  2. Alice sees documentation for example::really_useful_module from example version 0.17.0.
  3. Alice thinks this is worth revisiting, and bookmarks the page or leaves the tab open.
  4. Bob publishes version 0.18.0 of package example, which renames really_useful_module to rum.
  5. Alice revisits or reloads.
  6. Alice sees a 404 page that says “The requested resource does not exist”, and provides no navigation related to example at all.

This leaves Alice with no easy option to recover other than manual URL editing. It would be useful if the 404 page:

  • Acknowledged that the package and version exist, even though the specific documentation file does not.
  • Provided links to recover such as to the root of the version docs (https://docs.rs/example/latest/) and to a page where other versions could be browsed (https://docs.rs/crate/example/).
  • Extra fancy stretch goal: lookup the most recent previous version which had such a page and link to that.

Please note that I'm proposing that the 404 page contains useful links, not that it become a redirect to any of the above. Redirects are (in my opinion) bad UX in this scenario because they may confuse the user as to where they were and what they were previously looking at, and also, the fact that a new version was published that deleted a module is potentially highly relevant information.

kpreid avatar Jul 28 '24 04:07 kpreid