Throwing your own other comment back at ya :D
If docs aren't maintained and curated then it doesn't matter if they are in a wiki, word docs, printed pages in a file cabinet or in the repository as markdown files. Getting team discipline around updating docs is the solution, the place where they are stored is sort of trivial if that discipline exists (fwiw, I've yet to see that discipline).
With that said, there are times where docs in source control are totally viable, especially when their scoped to the repo they are located in.
How do you deal with cross-cutting concerns, docs that span multiple code repositories?
> some poor soul comes along and asks a question that's 5 years out of date because they found it on the wiki
This happens if there's docs in a git repo as well.
There may be longer write-ups, examples, etc. at the module level.
Documentation gets compiled into a docs.rs-style searchable website like so:
https://docs.rs/tokio/1.36.0/tokio/
Examples are compiled and run as part of the default CI toolchain.
So when a piece of documentation refers to some code that was moved or renamed, it is a bug to not update references in Rustdoc comments.
Comments can still get stale because some programmers write but don't read.
But they're right there on your screen next to the code you're updating.
