Teach, Don't Tell

When I come across bad documentation (which is often), by far the most common problem I find is that the information I needed just plain isn't present. Articles like this one really aren't helping. If you wrote a piece of software I'm using that doesn't make you my teacher. It makes you someone offering a contract, and what I need to know is what that contract says. The first duty of your documentation is to be complete and correct. Unless…

The most important thing I want from API documentation is that every method should have a minimal working code example. Minimal - the example should be focused on demonstrating how to call that specific method, with as little other code as possible. That way I don't have to puzzle which parts are essential and which are arbitrary. Working - if I paste the example code into a separate file and run it, it should work. Surprisingly many attempts at documentation…

This is a great read and it articulates my own frustration with the current practice-de-jour of "we write such readable code that we don't need documentation". While readable code is great, I still don't want to have to read the whole codebase to figure out how to use something. I've found it useful to take lessons from Kathy Sierra's excellent "BADASS: Making Users Awesome" book. Look, folks, people don't want to use your library because the library itself is awesome…