Can we Please Stop Changing the Documentation in Ways that Create Broken Links?

This is a major frustration of mine. I have had to update my bookmarks to Aurelia Documentation files at least twice since I started using the framework a little over a year ago. Various blog posts and Stack Exchange questions are plagued by dead links to Aurelia Documentation.

Today, the top Google search result for “aurelia collection observer” links to a 404 page:

I love the framework and I understand that the recent changes to the documentation site were done to improve the experience. However, there are strategies we can use to prevent the creation of broken links when updates are needed.

I would like to suggest that the Aurelia team implement some form of version control for the documentation site. It wouldn’t be difficult to implement and it could look something like this:

https://aurelia.io/docs_[v2.0.0]/binding/binding-observable-properties/

Therefore links to any Aurelia documentation page would continue to work even as new versions of the documentation are released. Just make sure to put a “This Document is Out-of-date” banner to the top of the page when you release a new version of the documentation and this should work fine.

Anyone else having issues with dead links?

7 Likes

This is a nice feedback. @EisenbergEffect

1 Like