Steve Losh's Teach, Don't Tell

141 tabs are open in my browser right now. Lots of them are "I'll read this later" tabs. One of them is Steve's "Teach, Don't Tell" article. It's a good read that explains many of the current trends in writing technical documentation, and why they're horrible. The trends are:

• "Read the Source" Trend
• No real documentation is provided. The source IS the documentation.
• Solely relying on this is bad because: The source is good for an expert of the tool already, but is next to worthless at introducing the tool to a novice.
• "Read the Tests" Trend
• The idea here is that since the tests actually use the tool in question, it should do a good job in providing examples to the user.
• Solely relying on this is bad because: While there are tests that cover normal use cases, many are for edge cases, which should, by definition, happen less than average.
• "Literate Programming" Trend, "Read the Docstrings" Trend, "Read the API Docs" Trend
• These three were covered separately, but the basis of these trends are the same: Documentation is added to the source code (or, the source code itself is made to be more readable). Later, tools can transform this documentation automatically into something that is more accessible than just navigating around source code files.
• Examples include JavaDoc, Doxygen, Docco, Python docstrings, and many more.
• Solely relying on this is bad because: Its a more elegant approach to "Read the Source", though still lacks information such as "what is this?" "Where to begin?" "How to use?" and more. However, these references become invaluable once someone is knowledgeable with the tool.
• "Read the Wiki" Trend
• Documentation can be written by the authors as needed. Typos can be fixed, extra information can be filled in, anything that is lacking in the documentation, can be done by anyone interested.
• Solely relying on this is bad because: It may be better than nothing, but it is more laziness on the part of the developers than anything else, because now it is removes the responsibility of writing good documentation away from the developer, and onto people that are interested in having good documentation. To paraphrase Steve, rather than the teacher asking for feedback on their lesson plan, its as if the teacher is giving the lesson plan to the students instead. Steve really hates these documentation wikis with a passion.
• Personally, if the wiki is done right (sadly, they are rarely done right), I believe it could be good documentation. At that point, the wiki would be less of a wiki and more of a CMS though.

In the end, none of these are BAD, per se, but if all that the user has is the ability to look at the source, and/or the tests, and/or the API docs, and/or lazy-and-unfocused documentation, then the developers have failed to provide documentation that can teach.

What I need to remember is that, it doesn't matter how great something I make is. If other people don't know how to use it, it will languish. Therefore, I should strive to make good documentation that teaches, and this requires effort on my part. I cannot rely on tools to automatically pull this information out for me.