I’ve been thinking a lot lately about code examples in documentation.
What makes a good code example in a docs set?
How much should we break stuff down? Do you want code examples that are in separate files so they’re easy to reuse, or one big file so you can run it easily?
How realistic should a code example be - should it show error handling?
If you need to run code in incremental steps, should those be in separate examples, or should we give instructions about where to paste it into an existing example, or should it be commented out but present in the original example?
Does a single line count as a code example?
It’s amazing how few industry best practices exist around code examples, when they are such an important component in docs that are meant to teach developers how to use your APIs.