Good documentation includes examples. Good documentation does not rely on examples. An example can provide a base to start from, a beginning point from which

Good documentation includes examples. Good documentation does not rely on examples. An example can provide a base to start from, a beginning point from which further hacking can ensue. However, an example, like a picture, can't say "ain't": Examples can only show you what you can do, never what you cannot do, or what you should not do. Further, examples are inductive, and it takes a massive amount of induction to get all of the rules of a system. However, once someone's done something, they've internalized it a lot better than if they've only read about it. Examples should, therefore, allow people to see the intended use of an API. How do the developers want people to use their API to solve problems? Documentation is permissive: "You can use this tool to do this." Examples are normative: "You should use this tool this way." Both are needed. I focus on examples because good examples are not as common as they should be.