News for hackers. Stuff that matters.
Re:The Surprising Power of Documentation by makeitdouble on Monday June 12, 2023 @01:46AM (#36288894)
> OpenBSD's man pages are one example.

OpenBDS's developer to user ratio must be less that 1 to 1000s. When you update one line of document, you're probably saving time for thousands of users accross years of use.

Most project I worked on had at most a few dozen people with an actual chance of reading the documentation, and the majority of them aren't users, they'll be reading all the code anyway because they're not in a position to blindly trust the documentaton.

Why should we calculate the ROI of the time spend on maintaining good documentation the same way in both cases ?

PS: I also think a distinction should be made between specification and documentation. It feels that both are conflated too many times.

Re:The Surprising Power of Documentation by allknowingfrog on Monday June 12, 2023 @09:37AM (#36293215)
ROI should always be a consideration. It's reasonable to argue the merits of documentation. It may even be reasonable to argue that most projects would benefit from increased documentation. Without knowing how long it will take to write it and how many people will use it, you cannot reasonably insist that writing more documentation should be a priority for every project.

Much like automation, the question should be phrased in terms of how long it will take and how much time it will save. https://xkcd.com/1205/