Keeping docs and code as close together as possible. Certainly same repo. But for instance one of pythons greatest feature is docstrings. Which has encouraged documentation in the code. Other than that document in comments. And things like openapi and sphinx to generate docs from code.
Low level docs such as foo() does x and raises error when y should be expressed as unit tests.
External to code docs should be limited to things like deployment process.design docs (part of point of which is their history should be versioned not changed.
Proximity is a big help, for sure. Cross-references, ideally checked mechanically, can be helpful in making things proximate to multiple points.
I very much agree with expressing assertions as tests. Doctest is an interesting point in the space, here. An idea I've had (and prototyped, but never quite got where I wanted) is a system where I can add references to tests as citations supporting claims in documentation, such that when the test fails the assertions it supports can be surfaced.
Also, documentation that is frequently used is typically thereby checked against reality, and necessary updates found quickly. But much documentation won't be sufficiently frequently used to rely on that.
There are many things that help. I'm always looking for more. Thanks for your input :)
Low level docs such as foo() does x and raises error when y should be expressed as unit tests.
External to code docs should be limited to things like deployment process.design docs (part of point of which is their history should be versioned not changed.