MIT neuroscientists have found reading computer code does not rely on the regions of the brain involved in language processing. Instead, it activates the “multiple demand network,” which is also recruited for complex cognitive tasks such as solving math problems or crossword puzzles.
Excluding code / separating code away from the documentation, doesn’t seem like a good idea to me. Code is much more concrete and unambiguous than normal language and I really want clarity and certainty from docs. Maybe for general overview and higher concepts code is not the way to go, but I think that is exactly how good documentation is written already.
But if you have an example of what you would envision docs to be like without (or separated) code then I’d be curious to have a look. Right now, it seems like that would be like the quick coding ideas I write to colleagues sometimes and ask for their opinions. Generally they are uncertain and ask for a concrete code example :)
Basically agreed that it’s often useful, though maybe some good candidates for analysis would be some of these medium articles that are riddled with embeds.
On the other hand, when someone on stackoverflow tries to write a long conceptual splainer in the middle of replies that are mostly code mode, I usually don’t have an appetite for it.
Next time I have to write some, I might pay some mind to it either way.