It's hard to argue with, especially if you've experienced using good documentation. OpenBSD's man pages are one example. It takes a little time to break the habit of checking Google first and instead checking the man page first (you eventually learn that you rarely need more than that).
The key word is "good" documentation. That takes time and effort 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.
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.
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/
All of the above. But as someone who writes documentation let me add, most programmers are bad writers.
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.
This issue around poor writing skills is something that I've thought/worried about for a while. At some level of seniority (the more junior the better IMO) we expect developers to write design docs. The inability to communicate clearly in those documents is a huge problem. Oftentimes misunderstandings and ambiguities are cleared up at design review, but then never reintegrated into the document, leaving two artifacts, the implementation and the design doc. These obviously drift over time, maintaining correspondence is hard. But when one only ambiguously described the other from the get go, then the documentation is broken. This too is technical debt.
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.
Agreed on your last paragraph. One of my mantras to coders, as a tech documentarian, was that "Incorrect documentation is worse than no documentation".
All of the basics of anything google-like: typo-friendliness with word forms and phrases, links to source, formatting of output, GUI, or not spamming the output with a dozen of lines of warnings that some man page files are missing.
Then a bunch more degrees that I could know about if the tool were more usable
The key word is "good" documentation. That takes time and effort 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.