Examples are the most important part of you docs sometimes. There are at least two reasons for visiting docs: * Want to understand generally how to use a new c

Examples are the most important part of you docs sometimes. There are at least two reasons for visiting docs: * Want to understand generally how to use a new concept, typically at the class level (or more trickily at the two-or-three-classes level), e.g. how do I create a thread? * Already familiar with the concept but want to do something specific, typically at the method level, e.g. how to test whether a string starts with a particular prefix? There was a good post on Hackers News a few months ago breaking down documentation visitors into four categories, so there's at least two more. I think examples are very important in the first case, typically you want an example led-approach to explaining new concepts. But examples are a lot less important for method-level questions, and are often (not always) totally redundant if you have really clear and precise information about the method and its parameters. Edit: But just to be clear, I agree that examples are really important and you should definitely put them in your docs (at the class level and above). Edit 2: Here's the article [1] and HN dicussion [2]. In that terminology, I was distinguishing "explanation" and "reference". The other two types are "tutorial" and "how-to guide". [1] https://web.archive.org/web/20200312211539/https://www.divio.com/blog/documentation/ https://web.archive.org/web/20200312211539/https://www.divio... [2] https://news.ycombinator.com/item?id=21289832 https://news.ycombinator.com/item?id=21289832