When you're documenting a project so other people can use it, whether it's a library or web service, one important thing to do is to give people good examples to work with. Not only does this save people time trying to cobble together their first working program, but it's also a good way to show how the library is meant to be used, instead of just what's technically possible.

Show the best way to use your library

For your main examples, the goal should be to show people the highest-level, easiest interface they can use to solve their problem. Try to make what the examples are doing extremely obvious.

Keep in mind that documentation doesn't need to just be an output of your coding process. Writing these examples can also inform your API design, by showing you the parts that are hard to express in a simple way. If it's hard to make a good example, consider changing your API to make it easier.

However, make sure your examples are actually showing enough to be useful. Documentation for a database library should show how to pass parameters and use results. If your only example is how to execute literal SQL with no result, you're not really showing users a solution to a real problem. For an HTTP library, it's not enough to show a single GET request to a static URL; show your users how to use query and form parameters, how to set headers, and how to use any nice features to make that easier (for example, if sending JSON automatically sets the Content-Type header).

Don't leave things out

A lot of people like to leave error handing out when they write examples because "it makes the code cleaner". People reading your examples don't want clean code, they want to know how to use your library correctly. Showing them broken examples doesn't help with that.

Also, don't forget to show everything needed to make the examples work. If your library needs imports or includes, show them. If you need to pass flags to the compiler, say what they are. The point of examples is so people can see exactly how your code is supposed to work. If your users want to know specific information about a single function without any other noise, they'll read the API documentation. When it comes to examples, assume your readers are looking for complete and fully functionally code.

Keep your examples up to date

This is easier said than done, but it's very important that your examples actually work in the latest version of your library, and that they continue to represent the best way to use it. Examples aren't part of your stable API, so write new ones when you have ideas and throw old ones away as they become less useful.

If possible, use tooling to ensure that your examples continue working. One way to do this is to check your examples into the same repo as your library and make the CI system build and/or run them. doctest is a tool to extract examples out of Python comments and run them. This is meant for tests, but can also be used just to prove that your examples can execute successfully. Similar tools exist for C++, Java. If necessarily, it probably wouldn't be difficult to write a tool to extract tagged examples from your manual and run them in CI.

Also show examples of the weird parts

Now that you've got your main examples out of the way, showing the easiest and best ways to use your library, don't forget to document the low level interface and the weird functions that most people won't need. Depending on your API documentation, this may be less important, but I've found many cases where a set of functions is described as being able to solve my problem, but I can't figure out how I'm supposed to use them. If you have the time, considering making some examples for these as well.

This one is tricky because bad examples can be worse than no examples, so if you don't have the time to keep these up to date and they start to experience code rot, consider removing the examples rather than keeping bad ones around. Another option here is to point people at the code implementing your high level interface as an example of the low level interface.


Writing documentation is hard, but it can save your users a lot of time and help the popularity of your project. Hopefully these pointers will encourage you to write examples for documentation, and maybe make it a little bit easier.