News for hackers. Stuff that matters.
Re:Ask HN: How to Improve Documentation? by softwaredoug on Wednesday June 15, 2022 @08:47PM (#31761307)
Some principles I've found useful

* Avoid traditional documentation unless you absolutely need it

* Write good, readable tests! For developer users, this is the most 'honest' documentation to read

* Make other types of documentation as testable as possible. On our project, we maintain a series of jupyter notebooks for documentation heavily sprinkled with asserts to prove the state of the world exists as expected...

* TIMESTAMP - Prefer writeups, articles, blog posts, etc with timestamps over 'documentation' that promises to be current - this way its known when the information was relevant, and it's expected things grow out of date (like picking up a 1 year old book on a technology). If someone finds it useful and wants to update it, they can update the timestamp. Otherwise, its still a useful bit of context for a given snapshot in the past

Re:Ask HN: How to Improve Documentation? by shreythecray on Monday June 20, 2022 @06:18PM (#31816884)
What do you mean by "traditional documentation"?