Comment by WCSTombs

I completely agree. When the docs are in the same repository as the source code, at least you can keep the documentation atomically synced to the code. No other method allows this (not counting setups with Git submodules, which is the same thing with more steps), and that should be an immediate dealbreaker.

Docs being updated to reflect the code can then (and must, IMO) be a blocking constraint on all pull requests.