Programmer Humor

How many dictionary lookups deep are people reasonably expected to go? Depending on the reader, there's just some level of complexity that isn't accessible any more. Add to that the diversity of mental models and approaches people take and a semantic structure intuitive to you just won't work for someone else, no matter what words you use. Don't get me wrong, you can't cater to everyone and I'm not sure you should if you could.

I understand that your target audience are typically people already familiar with or at least invested in the subject matter, in which case leaning on a presumed funamental understanding and a willingness to fill gaps is sensible. You don't want to bloat your docs by repeating things your most relevant readers already know.

In doing so, you "sacrifice" the accessibility for less versed people. In a perfect world, we wouldn't have to choose and everyone would get an explanation suitable to their own level of understanding and background. Alas, our world imposes limits on our knowledge, abilities, time and energy. Readers and writers alike should be aware of those limits, both in themselves and in each other.

I feel like "Skill issue" understates the complexity of the combinatorics the diversity of human minds produces. It's a human issue that might never be perfectly solvable. Your solution is good and appropriate, and that has to be enough.

My point is merely that we should be aware of the downsides of our choices and make that tradeoff consciously.