Documentation is good, so therefore more documentation must be better, right? A few examples where things may have gotten out of control.

A fine example is the old OpenBSD install instructions. Once you’ve installed OpenBSD once or twice, the process is quite simple, but you’d never know this based on reading the instructions. Compare the files for 4.8 INSTALL and 5.8 INSTALL. Both begin with a brief intro to the project. Then 4.8 has an enormous list of mirrors, which seems fairly redundant if you’ve already found the install file. Followed by an enormous list of every supported variant of every supported device. Including a table of IO port configurations for ISA devices. Finally, after 1600 lines of introduction we get to the actual installation instructions. (Compared to line 231 for 5.8.) This includes a full page of text about how to install from tape, which nobody ever does. It took some time to recognize that all this documentation was actually an impediment to new users. Attempting to answer every possible question floods the reader with information for questions they were never planning to ask.

Part of the problem is how the information is organized. Theoretically it makes sense to list supported hardware before instructions. After all, you can’t install anything if it’s not supported, right? I’m sure that was considered when the device list was originally inserted above the install instructions. But as a practical matter, consulting a device list is neither the easiest nor fastest way to determine what actually works.

An example of nerdview signage. “They have in effect provided a sign that will tell you exactly what the question is provided you can already supply the answer.”

In the end, I think “copy diskimage to USB and follow prompts” is all the instructions one should need, but it’s hard to overcome the unease of actually making the jump. What if somebody is confused or uncertain? Why is this paragraph more redundant than that paragraph? (And if we delete both, are we cutting too much?)

Sometimes we don’t need to delete the information. Just hide it. The instructions to upgrade to 4.8 and upgrade to 5.8 are very similar, with a few differences because every release is a little bit different. The pages look very different, however, because the not at all recommended kernel free procedure, which takes up half the page, has been hidden from view behind some javascript and only expanded on demand. A casual browser will find the page and figure the upgrade process will be easy, as opposed to some long ordeal.

We can also compare the sysmerge sections. The old guide has a big section devoted to manually performing the operations that sysmerge now does automatically. Improvements to sysmerge obviate the need for such instructions. Sometimes the best way to improve documentation isn’t just to remove the documentation, but to remove the need for the documentation. OpenBSD is somewhat anti-HOWTO, so when a HOWTO starts growing in the documentation, it’s a sign something is wrong.

Finally, nearly every upgrade guide has a list of files to delete. After all, deleting stuff is how progress is made. Behind the scenes, however, there has been a policy change in what files are added to these lists. Only files that could affect the upgraded system are scheduled for removal. In 5.8, sudo was deprecated. It’s listed for removal because leaving it behind could have security implications, or cause confusion if reinstalled from ports. The 4.8 list includes a great many header files of no particular importance. Leaving them behind wouldn’t cause trouble, and their inclusion only makes the list seem larger. We can be proud of our deleted code, but no need to gloat about it. Further to this point, the benefits of the shorter list are more likely to be obvious to the user, while the longer lists are mysterious and confusing. Nobody likes following instructions they don’t understand.

Sometimes it’s just a tiny detail that’s overspecified. The apmd manual used to explain exactly which CPU idle time thresholds where used to adjust frequency. Those parameters, and the algorithm itself, were adjusted occasionally in response to user feedback, but sometimes the man page lagged behind. The numbers are of no use to a user. They’re not adjustable without recompiling. Knowing that the frequency would be reduced at 85% idle vs 90% idle doesn’t really offer much guidance as to whether to enable auto scaling or not. Deleting this detail ensured the man page was always correct and spares the user the cognitive load of trying to solve an unnecessary math problem.

For another humorous example, it was recently observed that the deja-dup package provides man page translations for Australia, Canada, and Great Britain. I checked, the pages are in fact not quite identical. Some contain typo fixes that didn’t propagate to other translations. Project idea: attempt to identify which country has the most users, or most fastidious users, by bug fixes to localized man pages.