Here's my first post on here. I wrote it before I ended up setting up my blog. I figured I had to start writing blog posts some point, and by writing my ideas on things as I encountered them, I'd remember my ideas better.
I started writing this after looking at some GitHub API docs, and not understanding how to read files from a private repo. I ended up looking around, realizing the answer after looking at a GitHub gist, and thought I was an idiot for not realizing it sooner. But I realized that even if I was being an idiot, I had read the page and the OAuth page, and knew they needed to fit together somehow: all I needed was an example.
When writing documentation for our own programs, we're biased. Very biased. Not only do we know how to write code or use our software efficiently, but we also know exactly how it works the way it does and the processes it takes.
We sometimes even assume that our software is meant to be used in a specific way and will never be used in inefficient/impractical method X. Why? Because X is insecure, or X would never happen if documentation was followed, or there are more efficient tools than the one we've made, that are actually built for doing X.
Sometimes, or more often, almost always, the user won't be reading all of the documentation. Maybe barely any of it. Or maybe the docs you wrote were bad, or incomplete, or assumed the user knew things they didn't.
That's what examples are for
Examples at their most basic level are beginner friendly. For beginners, writing a program, and walking through it, explaining as you go, is more important and valuable than providing each function call along with a detailed desicription of what it does.
We all learn by being given examples. Like babies learn from hearing adults talk, we learn how to use a language, library, or framework, from seing well-structured, thought-out examples and their given or implied use cases. And babies babble before they learn to talk, just like we understand small bits of code before we understand a program as a whole. But sentence structure, proper word usage, etc., take much longer.
It's clear that the solution is more frequent and more thorough examples. You don't need to give five examples for every new concept you introduce. But you could.
Since I'm writing about giving examples, it's only fair that I give an example on how to give examples. I started out learning JS, and no other resource was as consistently thorough and complete in its documentation as the Mozilla Developer Network.
Consider for example, the ternary operator. It's simple enough, if you're used it multiple times. It's just an if/else statement with a different return value on true/false. It's dead simple, right? Not to all beginners. Ask a friend who's just started programming if they can understand it and use it properly just by you explaining it to them. Chances are, they won't.
If you look at the MDN docs on it though, it looks like 2/3 of the relevant words are examples alone. And half of the other words are explaining exactly what the examples are doing. This is great documentation, and it's not because of just the description of the functional requirements, because you probably included something along those lines when you explained it. It's the examples, the walkthrough of what the example does, the thoroughness of the examples, and the sheer number of them, which helps them cover so many use cases.