Code examples
This book is primarily aimed at developers, so I assume that whatever you want to document needs users to create some code. Explaining a technical concept with code examples is one of the more common elements to add to documentation and something readers are used to seeing. They probably expect them. However, rarely are code examples useful or, worse, even functional. How often have you followed a tutorial, copied and pasted a series of code snippets into an editor, to run it and find that it didn’t work? I would guess it’s quite a common and frustrating experience.
If someone is motivated to learn (or has no choice) your project or product, they will continue experimenting and trying to figure out what’s wrong. But they will give up and move on to a competitor if they aren’t motivated. If your project is open source, they might create an issue or a pull request. More often than not, you may not even know there’s a problem until someone...
