I spend an inordinate amount of time searching for information about macOS. Whether I am researching the answers for my section in MacFormat magazine, or trying to solve my own problems here, I am also daily reminded of Apple’s wholesale failure to provide consistent and complete documentation of its flagship product.

This never used to be the case. In the days of classic Mac OS, when print publishing was growing as a result of Macs, Apple published an exemplary series of books under the banner Inside Macintosh, some of which volumes are still in a pile under my desk. It did so despite Mac OS undergoing quite rapid evolution: System 7.0 in 1991, 8.0 six years later in 1997, and 9.0 just two years later in 1999.

I don’t know how many technical authors were employed by Apple at that time, but I suspect it was a far higher proportion of total staff than it is now.

Since then, Mac OS X, then OS X, now macOS have become immeasurably more expansive and complex, many more people use Macs, and they need much more support. Yet Apple’s documentation for users and those supporting users has all but dried up. Even when you look through guides for developers, few have been substantially revised for several years, and many are completely out of kilter with El Capitan or Sierra.

It’s very easy to blame users for not making best use of the information that is available, or to recommend everyone to contact Apple support. But I read, and answer, a relentless stream of questions from users who – for example – did not realise that they had to recharge their Magic Trackpad 2, never knew how to launch an app from the Dock, or couldn’t manage their Photos library.

Apple changes things without explaining the new system properly, and without providing us with suitable new tools. One of the best, and most shocking, examples of this was the introduction of the new unified log in Sierra. Almost a year later, Apple has not provided us with an accessible utility which can browse past entries in the new log, nor any guide at all as to how to use or interpret new log entries. All the useful information is contained in the man page for the command tool log.

Much of the information available is outdated and now incorrect. There was a time when launchd – second only in importance to the kernel – controlled and orchestrated most of the services supplied in macOS. Now a large proportion of them are scheduled and dispatched by two systems, DAS and CTS, which are barely even mentioned in Apple’s latest developer documentation, a busy part of macOS which doesn’t even appear to have a name.

I’m afraid that there is no glimmer of light that Apple intends to change this situation. Indeed, with the next major release of macOS making its way through its last beta releases, there is a good chance that it will soon get even worse when we have to contend with the foibles of APFS and many other changes.

From where I’m sitting, there is only one way that we are going to get better documentation: to create it ourselves.

So far, open and collaborative projects have developed a great deal of valuable software. They have attracted a great many developers, some of them extremely talented, and have been a real success. But open-sourcing and collaboratively-developing software is only part of what computer users need. Most open source projects are proud to have user documentation which is an order of magnitude better than anything provided by Apple for macOS.

What Mac users need most is an open and collaborative project to document macOS. I’m happy to help make this happen, and to donate to it relevant material from this blog in a joint effort to take us all from the dark back into the light.