Open heinezen opened 1 year ago
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.
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.
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.
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