Teach, Don’t Tell
This post is about writing technical documentation. More specifically: it’s about writing documentation for programming languages and libraries.
I love reading great documentation. When I have a question and the documentations explains the answer almost as if the author has magically anticipated my problem, I get a warm, fuzzy feeling inside. I feel a connection with the writer that makes me smile.
I also love writing documentation. Being able to rewire the neurons in someone’s brain so that they understand something they didn’t understand before is extremely satisfying. Seeing (or hearing about) the “click” when a bunch of concepts suddenly fall together and make sense never fails to make my day.
This post is going to be about what I think good documentation is and how I think you should go about writing it. I’m not perfect, so you should take everything with a grain of salt, but I hope you’ll find it useful and thought-provoking even if you don’t agree with me about everything.
I’d like to say thanks to Craig Zheng and Honza Pokorny for proofreading this.
