So confident are they in their superlative design that most hardware and software vendors now provide minimal documentation: an elegantly coiffured card with impeccable typography and a couple of simple pictures.

They presume that, if something isn’t obvious, we can get an answer from others in a support forum, or just snatch it out of thin Google.

When the (classic) Macintosh OS was young, and growing slowly, Apple used to publish its exemplary Inside Macintosh reference books. As it took three years to progress from System 6 (Mac OS 6) to System 7, and a further six years to reach System 8, there was ample time for an army of technical authors to craft their prose, gather screenshots, and even assemble indexes. Most of those early manuals were written and published using Microsoft Word, so proud was Apple of the Mac’s publishing abilities.

With OS X, we have of course got used to electronic versions of documentation, rather than filling our shelves with hefty paper volumes. By the time that we had got to OS X 10.5 Leopard in 2007, the basic administration manual for OS X Server 10.5 had grown to 231 pages of PDF, with several supplementary PDFs covering the individual services in detail. At one time, I think I brought the total to over 2200 intense and informative pages.

Currently, with OS X Server 5.0.15, intended for a much wider range of users, including many who have never used a server before, documentation has reached a nadir. Advanced topics, like the Name Service DNS, get an external (web) page with a few dozen sentences and a couple of links to generic resources about DNS. There are some tutorials which look very friendly, a general support site, and that is it. Look for proper manuals, and those for OS X Server 10.5 seem to be the most recent that Apple released.

OS X itself gets ever more complex, but there are almost no manuals; most of its documentation exists in only in a labyrinth of Apple technical notes of varying vintages, or in nooks and crannies in the documentation provided for developers as part of Xcode. Its fragmentary nature brings piecemeal quality and accuracy.

For example, when researching Apple’s text-to-speech technology, the most recent documentation is almost ten years old, and does not even mention modern ‘advanced’ voices which do not appear to use the same MacinTalk-based engine. When I was looking for information about punctuation and other signs supported by OS X dictation, I discovered that I already knew more than Apple’s technical note admitted to.

There are inevitable problems in documenting such fast-changing systems, but – as software engineers and developers know well – if it is not documented, it remains obscure and is not fit for purpose. Surely Apple’s own engineers must have more detailed and extensive documentation, or they would forever be guessworking.

Others have also pointed out the many limitations of trying to work with documentation which can only be accessed online, or on your Mac. If your Mac won’t start up properly, how do you get access to information on what to do? Armed with another computer, iPhone, or iPad, you have a fighting chance, but the chances are you will then be struggling and starting to go down yourself.

It has always struck me as being peculiarly ironic that the only advice about restoring a failed Internet service is online, which is of course the last place that you are likely to be able to find it.

Seeking help from others online is also a mixed blessing. Sometimes you strike lucky, the right person happens on your plea for help, and they provide sage advice which solves the issue. Browse any support forums, official or third-party, and you will see countless questions which have either not be answered at all, or the suggestions provided have been of no help. One recent idea for getting a better response is to deliberately post a wrong answer, as you can rest assured that plenty will then chip in to correct it.

No matter how whizzy the designers and developers think things are, documentation needs to be engineered back into the development process. Users are not deterred from products because they have extensive and exhaustive documentation. I have been a little unfair in concentrating on Apple’s shortcomings here, as the zero docs disease is not just industry-wide, but now almost universal to all products. But for any company to put more effort and expenditure into its packaging than its documentation is hardly user-oriented.

Let’s go back to proper documentation for users, please, and let’s take some pride in its accomplishment once more.