The path towards better documentation

[m4tx]

The current state of the guide (https://cot.rs/guide/latest/) is not great, to say the least. It's often outdated, not very complete, and doesn't describe many basic concepts. A great web framework should have great documentation, and we aren't quite there yet at the moment. We're, however, at the stage where many core APIs have been stabilized enough to write documentation that will last for relatively long time.

Problem

I think the core problem with the guide is that it lives in another repository. Therefore, whenever someone makes a change, they (including myself) usually don't care to update the guide. We then rush this right before the release, which is not very productive. It would be better if we forced changing the guide along with the code change.

Another big problem is that the guide doesn't have any sort of automatic checks. Whenever the framework changes, the guide might become out of date and nobody will notice until they actually try to follow the guide.

One smaller (yet still important) problem with the current state of things is that because we have separate directories for the docs for each version of the framework, the commits in git usually do not represent who has written the docs. Solving this would be nice to properly attribute the actual authors.

Solution proposition

The idea to solve these problems is to rework how we build the guide.

1. Instead of having cot-site as the repository where the guide lives, the guide should live in the main repository (e.g. inside a newly created docs directory). This would allow us to force on the PR authors to change the guide when they introduce changes.
2. Because the guide will live on the main repository, we could introduce some sort of automatic tests. I recommend reading Luca Palmieri's blogpost for an inspiration about this, but basically the idea could be that for each code snippet in the guide, we could take the default project template from cot-cli, append the snippet, and check whether it compiles. This could be further improved, for instance with rustdoc-style #-prepended lines that are not displayed in the final docs. The idea is, we should have some sort of way to at least check whether the code can be build. This would force the guide to never go out of date.
3. cot-site should be changed so that it should only contain the "engine" for building the website, instead of hosting the content. The content should be pulled using git submodules from the main repo. It should also be possible to build the website with the latest docs directly from the main repository. Because the docs will never be copied across directories, this will also solve the git attribution problems.