I got a lot of interesting and thoughtful replies to my post yesterday about code examples in docs, but I've got a hot take on one of the themes that emerged... that code examples should vary depending on the intended audience. (Skill/experience level, etc.)
That's a common convention in technical writing, but I have never seen this done effectively with code examples.
I have never seen a docs set that allowed me to specify my skill level - i.e. experienced developer who is new to this tech versus new developer. I have also never seen a docs set that effectively tailored examples for different experience levels.
I have seen docs marked "Beginner," "Intermediate," "Advanced." And I've seen from experience that docs writers are bad at assessing what should be in each skill level when it's generic like this, and developers are bad at self-selecting their skill level.
So - I think this theory that code examples should be different for different audiences doesn't hold up to any real-world docs sets I've seen.
Do you have a favorite docs set that you think actually implements this?
(I also have thoughts about the maintenance burden this requires. I made a proposal in my org earlier this year to single-source different levels of code examples from a single tested example, but haven't had a chance to go beyond proposal with this yet. I think it would be very easy to create a major maintenance burden if this isn't single-sourced from a tested example set.)