> In the idealized straight-forward elaboration, then, all docs would live in the repo, but I haven't worked with a team that was on board with that

In case you're thinking about productizing your work I just want to give you a little encouragement that there are a lot of companies OK with having docs live alongside code. See Google's g3doc [1] for example. See also the docs as code movement.

[1] https://www.usenix.org/conference/srecon16europe/program/pre...