Improving the Quality of a Website

Spellchecker and Grammar

I am not an English native speaker and also not really talented with foreign languages. I should find ways to improve the structure of my articles and remove typographical errors.

The IntelliJ environment provides a build-in spellchecker the Grazie plugin to detect grammar errors. The plugin uses LanguageTool to provide hints. The spellchecker supports the extension of supported words. When writing technical texts, assume that quite a few words are not part of a standard dictionary.

The grammar checker cannot be easily tailored and has limitations.

For example, the expression Scrum Master is often flagged as politically incorrect. You get the hint that the word master should be avoided. This hint is quite useless in the context of the Scrum approach.

Eliminate Dead Links

The biggest advantage of a website is the capability to link information to the reference document or the official description. As a user, I just need to click the link to access details. It is quite important that a hyperlink works when the user clicks on it.

Sadly, website authors do not fully understand the concept of universal resource locator URI Linked pages work well if links are defined as permanent uniform resource locators.

We want to improve the experience of our users. All links of a website should regularly be validated. Dead links should be eliminated.

A dead link in our websites is removed. A footnote is added to document the removal and to provide a hint about the information previously referenced through the connection.

The idea is to provide a primitive history to the interested readers.

The available utilities to check dead links have limitations or require expensive subscriptions. On a rainy day, we decided to write our small utility tailored to our website and needs.

The utility provides the following features:

Recursively parse our website and extract all links.
Ignore all links to javascript libraries: jQuery, lunr, mathJax.
Ignore all links to ebook on Amazon website. The Amazon site refuses connection requests as soon as the frequency hints to a program.
List all failed connections with the source page, the link, and the error message encountered.

Bibliography

We often write technical articles.

References are provided and follow a standardized format for all bibliographical references. We want to increase the comfort for the user. Most of the references contain a link to the book description on the Amazon website ^[1].

Asciidoctor provides a nice extension to include bibliographical references in our articles. The extension is called AsciiDoctor BibTeX and supports the inclusion of bibtex files.

It supports the IEEE format for the bibliographic references, which is my preferred format.

We provide a bibtex file with all the books we bought and referenced in our articles. Feel free to use it. It is released as all our articles under creative commons attribution 4.0 international CC BY 4.0 ^[2].

Statistics

I welcome data helping me to better understand the structure of my technical website.

I find it interesting to know:

Year of publication
How many articles did I write in a specific year?
How many article references are defined in an article? Average number of articles references are published per blog in a specific year?
How many book references are defined in an article? Average number of book references are published per blog in a specific year?

Year	Published Blogs	Referenced Blogs	Average	Book References	Average
2016	13	9	0.69	23	1.77
2017	15	16	1.07	4	0.27
2018	20	28	1.40	22	1.10
2019	13	27	2.08	8	0.62
2020	14	51	3.64	13	0.93
2021	32	64	2.00	43	1.34
2022	25	66	2.64	84	3.36
2023	28	111	3.96	78	2.79
2024	22	82	3.73	75	3.41
Total	182

Over the years, we cited 130 different books in our articles.

Links

[1] Creating a Technical Website with Hugo and AsciiDoc. Marcel Baumann. 2020.
[2] Improving a Static Website build with Hugo and Docsy. Marcel Baumann. 2021.
[3] Support Comments for Static Hugo Website. Marcel Baumann. 2020.