It should not be surprising when a link in the docs navigates to an external resource.
Current Behavior
It is surprising when a link in the docs navigates to an external resource.
Context
There's an extraordinary number of external hyperlinks to RFC's and other sites scattered throughout the Spring Security docs. They are styled and linked inline the same way as internal and inter-project links, placing unnecessary cognitive load on readers.
One such example of a surprising hyperlink can be seen near the top of this page.
Now we can consider how Bearer Token Authentication works within Spring Security. First, we see that, as with Basic Authentication, the WWW-Authenticate header is sent back to an unauthenticated client
One link will take you to another section of the documentation, while the other link will jarringly remove you from the documentation and take you to an RFC text on another website, and there's no indication which one it is unless you hover over the link and double check.
Some sites such as Wikipedia enforce a "new page" icon similar to ⧉, but perhaps that would cause excessive noise. This SE answer proposes a reasonable middle-ground between no delineation and a strict policy like Wikipedia: https://ux.stackexchange.com/a/14897
I'm not sure what a solution would look like but wanted to bring the usability issue to attention.
This was originally reported at https://github.com/spring-projects/spring-security/issues/14065. The description below uses Spring Security as an example but can also apply to any such project.
Expected Behavior
It should not be surprising when a link in the docs navigates to an external resource.
Current Behavior
It is surprising when a link in the docs navigates to an external resource.
Context
There's an extraordinary number of external hyperlinks to RFC's and other sites scattered throughout the Spring Security docs. They are styled and linked inline the same way as internal and inter-project links, placing unnecessary cognitive load on readers.
One such example of a surprising hyperlink can be seen near the top of this page.
One link will take you to another section of the documentation, while the other link will jarringly remove you from the documentation and take you to an RFC text on another website, and there's no indication which one it is unless you hover over the link and double check.
Some sites such as Wikipedia enforce a "new page" icon similar to
⧉, but perhaps that would cause excessive noise. This SE answer proposes a reasonable middle-ground between no delineation and a strict policy like Wikipedia: https://ux.stackexchange.com/a/14897I'm not sure what a solution would look like but wanted to bring the usability issue to attention.