CommunitySolidServer icon indicating copy to clipboard operation
CommunitySolidServer copied to clipboard

In the documentation, use meaningful links

Open Antoine-Zimmermann opened this issue 8 months ago • 0 comments

This is not actual bug, but in the documentation there are many links that read "here" or other non-informing phrases. This must be avoided. For instance, on the homepage, it is written:

An introductory tutorial that gives a quick overview of the Solid and CSS basics can be found here.

The hyperlink is not saying anything useful and is attracting the eyes, while the meaningful information that anyone should attracted to is "An introductory tutorial" or "tutorial that gives a quick overview of the Solid and CSS basics", or even "quick overview of the Solid and CSS basics". These phrases more accurately describe what the linked page is about. E.g.:

Our introductory tutorial gives a quick overview of the Solid and CSS basics. This is a good way to get started with the server and its setup.

Other links occur on single words that are insufficient to identify what the link is about. For instance, on the description of the main features of CSS, one can read:

See this tutorial and/or this example repository for more information on that.

Is it the introductory tutorial or another one? Who knows, until you click on the link. Instead, write, e.g.:

The tutorial on customizing configurations and the "hello word repository" provide more information on that.

Please revise all the documentation pages with meaningful links.

Important: Note that this is not a cosmetic change. It is an accessibility issue that is referenced by the W3C and many Web designer professionals. Solid is about Linking data, so you must get the linkage right.

Antoine-Zimmermann avatar Feb 17 '25 16:02 Antoine-Zimmermann