-
-
Notifications
You must be signed in to change notification settings - Fork 1.1k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Make outdated documentation more obvious #1526
Comments
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. |
I would think of all the subsystems as independent modules and try to document them internally as much as possible. Then make the “external”
Good example for an architecture doc: Good read about it: I think that if you make the documentation too small in scope within the I would probably rather write small scoped thing in e.g. 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 The advantage is, that you then can also test if changes have been made to the readme when files in, e.g. 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 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
The text was updated successfully, but these errors were encountered: