Ive been doing developer relations at Google for 4+ yrs now and the points about code snippets in this article are great. Let me add another one though.

Find a way to pull your code snippets from real code.

What I mean is, write the code snippets somewhere that you can use a your normal coding tools and make sure they all compile. Publish this repository of snippets on GitHub or similar. In your doc system, have the docs pull the code snippets from the repository at page generation time. This repository should have basic CI to make sure the code and dependencies are valid.

If you write snippets directly in markdown or html, they will eventually be wrong. Even if they start correct, it will be a real pain to update them for v2 of your API. Every team I've ever seen that thought they were the exception to this rule was wrong.