Thoughts on documenting macOS: do we have a project?

Last weekend, I proposed that the time had come for a community project to document macOS Sierra and High Sierra for users, support folk, and system administrators. This did not fall on deaf ears: within a day or so, my plea was read by over twenty thousand of you.

I am very grateful to those of you who have taken time and effort to comment here, by email, and elsewhere, and particularly to the many who have already volunteered to help.

Unsurprisingly, no one suggested that Apple’s documentation was sufficient. Several pointed out other worthy alternatives – excellent resources in their own ways – none of which actually meets the need. Several pointed out Jonathan Levin’s superb technical reference, the volumes of the ‘New OS X Book’. Many have suggested various online resources, particularly StackExchange.

Many people have pointed out, perfectly correctly, that we should not be doing Apple’s job. It has the resources of quite a substantial national economy, and if it cannot find a tiny proportion of its revenues to hire decent technical authors and document its own products, then it should be ashamed.

I agree with much of what has been written, but we cannot escape some basic facts:

  • Apple once had exemplary documentation for users, support folk, and developers.
  • macOS is now largely undocumented, at least by Apple.
  • Users – particularly advanced users – and those supporting macOS systems have no coherent, up-to-date documentation available.
  • Apple is fully aware of this situation, as it is one of its own choosing. No amount of bug reports is likely to bring change.
  • There is no sign whatsoever that Apple intends improving its macOS documentation. Indeed, as with its developer documentation, it is in steady decline, with useful guides now badly out of date.

We have two options: we can carry on watching this decline, and struggle more and more when trying to solve problems with macOS, or we can organise and produce our own documentation. No one else is going to do it for us.

The documentation that we need is not a huge compilation of Q&As, nor step-by-step recipes for performing everyday tasks. There are many of those available, and the few remaining Mac magazines and commercial websites make those their stock-in-trade. We need both conceptual and formulaic content, so that we can understand what is happening in macOS, and can tackle problems systematically.

Although this documentation should be of value to all Mac users, I don’t think that it should be aimed at developers, or specialist sectors such as security or forensics.

This is not an easy task, but I believe that within the Mac community there are many of us with knowledge and understanding which we can pool, and present in an accessible online reference to macOS, which meets the needs that Apple won’t.

I think that this should be a community effort, and non-commercial. It will inevitably have costs – and, as always, the greatest real cost will be the human knowledge and effort put into it – but I think that there are ways in which we can cover those without peppering the site with ads, or seeking commercial sponsorship which could call into question the independence of the information and advice.

For a start, I’d like to put together a small group of us to steer the project, make decisions such as the software platform(s) to use, and then to act as editors. I don’t want it to have a single leader: I think that we should be able to proceed together by consensus. For several years I worked in standardisation, where consensus is all, and good convenors ensure that groups of experts run projects in collaboration.

Our only fundamental rule should be that our working language is English (from any continent!), as I regret that other languages would be a great challenge for me, and for most of us, I suspect. That does not exclude the future possibility of translating the site into other languages, but I think it’d be wise to flourish in one before we take on any others.

I think that we are most likely to be successful if we confine ourselves, at least for the moment, to macOS and its immediate tools, excluding Apple’s user apps. I think that it is important to include some apps such as Safari which are not, strictly speaking, parts of macOS. I think that we should start by picking some important areas, such as backup and Time Machine, native file systems, scheduled and background tasks, startup and extensions, for which we can produce thorough accounts relatively quickly, perhaps by the end of the year (updating them to cover High Sierra when it comes).

That would give a core of information which would be of immediate value to users, from which we could then grow, as the project enthused others.

I mentioned platforms. I have limited experience of suitable software – a little Drupal some time ago, and a smattering of Wikis – and am keen to involve someone who has good experience of CMS and Wikis so that we can get a site up and running early, to facilitate discussion.

These are only my personal thoughts. They are not requirements or rules, and I’d love to discuss them here, with those who are interested in getting involved. They perhaps give you a better idea of what I have in mind. I now invite you to discuss them here, in the first instance, and to invite others who might be interested in taking part to join us here.