Maybe this could inform how documentation is written. Clearly separate out the language from the code and don’t make readers switch modes throughout the page (or just don’t include code in the documentation). I dunno.
Well noted. That’d be an interesting use for such findings.
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.
