Continuing to think about code examples in documentation, and I'm starting to ideate around some core concepts, or "Pillars" of code examples:
- Coverage: How complete is the code example coverage within the documentation? Does every API have the right quantity of code examples, demonstrating usage at the right levels of abstraction? Do code examples show not just the API itself, but how to get/form the arguments for the API, and how to work with whatever the API returns?
- Maintenance: Are the code examples tested? Are tests run with every version update/code example change? Do tickets get generated to update code examples when APIs change? Is there a governance policy for archiving code examples for old versions?
- Discoverability: Can developers find your code examples? Are they available not just in your documentation, but in GitHub and/or LLMs? Do third-party sources have information that leads developers back to your code examples - i.e. package manager release notes, READMEs off your website, etc.?
Curious for your thoughts, #TechnicalWriters and #Developers - do these pillars resonate with you? Are there things I'm missing, or things you think are particularly important?