Re:Essential elements of good documentation
by shadowfiend on Wednesday October 23, 2019 @05:05PM
(#21339009)
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.
[ Parent
| on HN ]
Re:Essential elements of good documentation
by mjw1007 on Wednesday October 23, 2019 @05:22PM
(#21339141)
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.