5 ms·
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/ http://stevelosh.com/blog/2013
by shadowfiend 7y ago
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/ 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.
- mjw1007 7y agoIt'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.