Docs front page, structure and organisation

[OsirisTerje]

Our docs site could need a facelift.

Right now it is hard to navigate, and hard to find what you're looking for, at least for first-timers to the docs. There are also a lot of older documentation, and some that should have been updated. The terms we're using are also in some places too internal and not so much user oriented.

I've been looking at different sites, and I ended with something like

By organizing our documentation, we likely won’t need to make significant changes. It may simply involve adjusting some wording and terminology while ensuring that our different groups are less technical and more user-oriented.

I created a rudimentary sketch like this:

I filled out some text in the first one, to showcase how we could rename a few of them. We could also break the Reference there into:

• Attributes
• Fluent Assertions
• Classical Assertions

Very few people relate to the term Constraint model, it is mostly internal. They look upon that syntax as a fluent variation.

[mikkelbu]

I think Sean had similar ideas especially about making it more user-oriented as much of the documentation is quite low-level at the moment (and sometimes hard to find).

It can be that restructuring the front page and the content does not require significant changes, but I think an overall cleanup of the docs site is a large task, so the more we can split this into smaller tasks/steps the better. So it can be that just starting with just the frontpage is a good first step.