Example-first Documentation
When I read through your (library|module|framework)’s documentation I will skip everything and scan until I find the first example.
The one unifying thing about many programmers is that they’re driven towards problem-solving, and they’re going to have a goal set when the finally reach your documentation. Documentation that aims to identify those goals and solve them as directly as possible is the best documentation. Users want the fastest way to prove and/or disprove their hypothesis.
The most direct way, you might imagine, is examples. Lots of examples. Everywhere. Nothing comes close to how useful actual usage is.
Two Common Ways I Use Documentation
- Checking how closely your examples match my intended use case. Everyone has a mental model of how they think a particular library will work prior to using it, and they will try to navigate to the right pages by searching for terms related to that. If this mental model is wrong, it’s important to know why that is and provide examples for what the alternatives look like.
- Attempt to install your software in a variety of ways I already know, and fall back to reading the “Getting Started” page when that doesn’t work.
More specifically, if users can’t see the actual functions or classes they intend to use demonstrated, they will avoid your framework entirely.
Although you’ll see more seasoned engineers throw around “RTFM” or other phrases extolling the virtues of painstakingly reading the manpages of a particular tool, but I will always have a shorter-term goal in mind than holistic understanding. Most documentation is intended as reference, but there still exists a large spectrum of user experience in navigating that reference information.
Reasons Whey They’re Looking For Examples
- Starting off and want a frame of reference.
- Users know what an implementation might look like, but don’t know what it’s called.
- StackOverflow-inspired copy/paste-heavy workflow.
- Asking for help on the internet sucks.
- Asking for help from your coworkers can suck too.
If you believe it’s easiest to get started using a framework if the examples are good, then it’s truly the most user-focused way of helping your users out. It’s the quickest route from intention to implementation.
Model Your Docs After Successful Software
There are an endless number of under-documented pieces of code out there, and their success or failure is largely driven around how quickly users can get at the answer that fits their mental model of how your library works.
Leaving some examples of great examples-driven documentation here: