Make outdated documentation more obvious

[heinezen]

Checking whether our documentation is outdated is both hard for us and almost impossible for outsiders. However, we should at least somewhat ensure that the architecture docs are up-to-date, so no one wastes their time reading irrelevant stuff. I don't know if there's a best practice way to do this but I'll throw in some suggestions

• Add current release number to docs. Something like "Last valid for release: X.Y.Z". We would still have to bump manually before every release.
• Let buildsystem notify us of possibly outdated docs. This would require that we can associate code with the architecture docs.

[TheJJ]

maybe add a random identifier a bit like the pxdgen annotation to docstrings - that way docs and code can be associated. then some versioning can be added, just an incrementing number maybe.

e.g. doc:n60fafe4x90ka:42 and the 42 has to match in the docs -> can then be checked by grepping by doc:(...):(...), and comparing the last group.

[simonsan]

I would think of all the subsystems as independent modules and try to document them internally as much as possible. Then make the “external” /docs documentation rough and link it to the internal module documentation. This also has the advantage that people are not intimidated by the /docs documentation, but can dig deeper if they want to.

• “avoid going into details of how each module works, pull this into separate documents or (better) inline documentation.”
• “Do not directly link them (links go stale).
  • Instead, encourage the reader to use symbol search to find the mentioned entities by name. This doesn’t require maintenance and will help to discover related, similarly named things.”

Good example for an architecture doc: https://github.com/rust-lang/rust-analyzer/blob/master/docs/dev/architecture.md

Good read about it: https://matklad.github.io/2021/02/06/ARCHITECTURE.md.html

I think that if you make the documentation too small in scope within the /docs folder, it is counterproductive because it becomes overwhelming pretty fast. Basically the point is to give the reader a rough overview to understand where, how, what, and why. But IMHO, anything concrete should be as close to the code/module/package as possible.

I would probably rather write small scoped thing in e.g. https://github.com/SFTtech/openage/tree/master/libopenage/event/Readme.md or https://github.com/heinezen/openage/tree/master/libopenage/renderer/Readme.md

These “sub-readmes” currently do not exist, for example.

I personally think that would make the most sense. Then put stuff in there like a code map, bird's eye view etc.

The advantage is, that you then can also test if changes have been made to the readme when files in, e.g. libopenage/renderer have been changed.

We can still create a mdbook like “openage development handbook” (SFTtech/openage-dev-guide) where we collect all the separate articles as a summary of all the documents.

https://github.com/BurntSushi/aho-corasick/blob/master/src/lib.rs

This is the entry point for the aho-corasick library with its top-level documentation, which is shown on the libraries start page of docs.rs. I think this is one of the best documentation examples for it. And this is what I would think of for the /libopenage/<subsystem>/Readme.md kind of.

Giving an overview, usage examples for different use cases, lower level APIs, etc.