> which isn't really the place for explaining CS fundamentals about data > structures, or diving into use-cases and tradeoffs even at an intermediate > level
Why? The only negative side I see is the necessity to keep the relation to the actual object of the documentation relevant. You may say the need to write it in the first place is a problem, but it's not - we're not talking about anything mandatory here. All the generic CS-y info can be neatly mentioned in their respective paragraphs which most of the users will gladly skip without a second thought. The benefits are, on the other hand multiple: 1. It demonstrates the importance of theoretical basis, so it promotes knowledge. 2. The outside info can be too broad and have too much irrelevant information but in-house info can be specific. 3. You can explain the considerations leading to the current state of the code simplifying the work for any possible future contributors. Of course, you need moderation in all things, but it's hardly to become a problem any way soon. Besides, getting stuff out of the docs is much easier than getting stuff out of the code. Here's a fascinating read which is a nice example of what I'd consider TMI for the docs and a kind of a blog I'd love to read about Nim things: <https://cglab.ca/~abeinges/blah/rust-btree-case>/
