Hacker News Reader

One of my favorite writings on the matter is Teach, Don't Tell, by Steve Losh: http://stevelosh.com/blog/2013/09/teach-dont-tell/ , including a rather savage takedown of wikis as a documentation mechanism. A bit idealistic, perhaps, especially for open source or single-person projects, but a good north star for doc work IMO.

View on HN

It's good advice, but I think that like a lot of such articles it's talking about how to run, when there's a need for more articles on how to walk.

That is, the first duty of technical documentation is to be complete and correct (at least for practical purposes). Once you've got that far it's time to pay attention to optimising it for the needs of your likely readers.

Reply on news.ycombinator.com