Polish documentation

[nipafx]

Proposed commit message:

Polish documentation (#681, #685 / #690)

* improve project description
* improve article titles, descriptions, and first paragraph (~> #681)
* sort navigation by title
* fix broken internal links
* use `====` for multi-line admonition boxes
* many small improvements (~> #685)

Closes: #681, #685
PR: #690

---

PR checklist

The following checklist shall help the PR's author, the reviewers and maintainers to ensure the quality of this project.
It is based on our contributors guidelines, especially the "writing code" section.
It shall help to check for completion of the listed points.
If a point does not apply to the given PR's changes, the corresponding entry can be simply marked as done.

Documentation (general)

• There is documentation (Javadoc and site documentation; added or updated)
• There is implementation information to describe why a non-obvious source code / solution got implemented
• Site documentation has its own .adoc file in the docs folder, e.g. docs/report-entries.adoc
• Site documentation in .adoc file references demo in src/demo/java instead of containing code blocks as text
• Only one sentence per line (especially in .adoc files)
• Javadoc uses formal style, while sites documentation may use informal style

Documentation (new extension)

• The docs/docs-nav.yml navigation has an entry for the new extension
• The package-info.java contains information about the new extension

Code

• Code adheres to code style, naming conventions etc.
• Successful tests cover all changes
• There are checks which validate correct / false usage / configuration of a functionality and there are tests to verify those checks
• Tests use AssertJ or our own PioneerAssert (which are based on AssertJ)

Contributing

• A prepared commit message exists
• The list of contributions inside README.md mentions the new contribution (real name optional)

[nipafx]

@jbduncan I made a bunch of changes to the resource and temp dir documentations. Would be nice if you had the time to look them over. 😃

[Bukama]

I didn't want to open that topic, bus as you did: Did you consider working on accessibility? 🙈

[nipafx]

I just ran two tools and the website is looking ok. Since there are serious considerations to replace it with something else (see junit-pioneer/junit-pioneer.github.io#26), I would not spend much time on it now.

[Bukama]

it looks okay except the hundres of contrast issue, from the code examples (as we also use asciidoc we have to search for a correct code style renderer [which is not task of asciidoc]), the layout tables and so on. But yeah we can tackle this in a different issue and focus here on content.

[jbduncan]

Great improvements, @nipafx! Just a small number of typos and clarifying questions, then I'd be totally happy.

[nipafx]

@jbduncan I added tests to verify the correct cleanup behavior in b11815a.

[nipafx]

As I see it, this is ready to merge. Let's run the full build and if nobody has any concerns, a maintainer can merge it.

[jbduncan]

@nipafx LGTM!