The Art of Writing Good Documentation: Teach, Don't Tell

Just come across this posting on how to write documentation, or more specifically, how to write GOOD documentation. It is by Steve Losh and called Teach, Don't Tell.

For example:

If you use many open source libraries you’ve undoubtedly encountered some whose README says something like “read the source”. Every time I see one, I die a little bit inside.

Source code is not documentation. Can you learn to be a guitarist by simply listening to a piece of music intently? Can you become a painter by visiting a lot of museums? Of course not!

This is one of the main reasons why we gave up on brilliant languages, frameworks etc- for example, this is the main reason why we had to give up on Opa sadly.

This is always the case when the experts in a language, framework, library etc are those who are developing the langauge, framework or library. They are so consumed by developing they forget the people who want to develop with their creation.

Teach the developers how to do something, don't fob the developer off with function signatures, obscure examples etc. If a developer is asking naive and "stupid" questions then there's probably a damned good reason why.

Maybe reading Zen and the Art of Motorcycle Maintenance should be compulsory for all?