Teach, Don’t Tell

Writing good technical documentation is hard, and that’s why you too often find yourself reading bad documentation. But how to write good documentation? Teach, Don’t Tell post is about writing technical documentation. More specifically: it’s about writing documentation for programming languages and libraries. There are many things you might want to accomplish, the writer is going to boil them down into a single statement: Teaching.

If you want to take a high school student and turn them into a computer scientist, how can you do that? You teach them. If you want to take a programmer who has never seen your library before and turn them into an expert user of it, how can you do that? You teach them! If the goal of documentation is to turn novices into experts, then the documentation must teach.

You should think of your documentation as a lesson (or series of lessons) because that’s what it is. When writing technical documentation you (usually) don’t have the advantage of having a one-on-one dialog with the learners. This makes it a bit more difficult, but not impossible as long as you’re careful. Your documentation needs to fill the role of both the in-person lessons and the textbook. The purpose of technical documentation is to take someone who has never seen your project, teach them to be an expert user of it, and support them once they become an expert.