4 ms·
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
by habosa 8y ago
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.
- franciscop 8y agoI did it the other way around; I wrote the tests within the code snippet (https://news.ycombinator.com/item?id=17837016 https://news.ycombinator.com/item?id=17837016). I was going to remove them when rendering, but in the end I thought they might actually be helpful and clarify things, so I left the tests within the snippets. For reference, here is the JS test builder (fairly rough): https://github.com/franciscop/server/blob/master/test/examples.test.js https://github.com/franciscop/server/blob/master/test/exampl...