To write good documentation you need to mix technical reference (the easy part) with user reference. The latter requires you to imagine where the user is at, and take them to where they understand. This is hard to do, and requires well, skills.
So a culture of documentation is great, but quality matters as much as quantity. Clarity, completeness and coherence are all legs of the stool.
However IMO an easy trap to fall into is to start documenting without a bigger understanding of the audience and the purpose of the doc.
A good way to start is to identify which of the 4 types of documentation you are working on.
https://nick.groenen.me/posts/the-4-types-of-technical-docum...
Personally I find it very easy to put too much explanation in the wrong places.
If you are fortunate, you can write code in an organization which has a high code quality bar, uses consistent styles etc. But it is rare (vanishingly so I nearly 30 years experience) to find the same bar applied to the design docs.
Then a bunch more degrees that I could know about if the tool were more usable
I mostly use man pages when I already basically know the program and need to do specific thing.
Even then I don't use man itself but usually a webpage of the manfile because of UX.
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.
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/
The key word is "good" documentation. That takes time and ffort to write, and it takes time and effort to keep it updated as things change. As the author notes, it will have to be something that is made part of the culture of the organization. And given that recent agile programming approaches proclaim that "the code is the documentation" and that formal, separate documentation is an impediment to productivity, you'll find that many developers will dig in their heels if asked to write documentation.
Bad, outdated, or just plain wrong documentation can be worse than nothing, as it tends to lead you to incorrect conclusions and beliefs about the system.