One of the ideas I enumerated in my documentation minifesto was to write words near the code, and then use tooling to publish the words where it was better for readers to find them.
There’s a lot to do to make that happen, including just deciding on the best approaches. OEP-19 Developer Documentation covers some of this, but it might need revisiting.