Apple Computer, Inc.

Good technical documentation does not need to provide drama, though some people manage to introduce that anyway—consider the second edition of Object-Oriented Software Construction by Bertrand Meyer, which builds up a case, like a consulting detective in a crime fiction novel, for a programming language based on a structured and consistent model of object-oriented software design. Only at the end does Meyer reveal that this language existed all along, and that it is… well, no spoilers here.

What good technical documentation does need to do is five things. Four of these are expressed clearly in the Diátaxis framework, and I have augmented that to fill in the obvious gap. Those things are:

  1. Guide you through learning the technology.
  2. Give you recipes for solving particular problems.
  3. Help you understand how the technology works.
  4. Provide a reference to the technology’s capabilities.
  5. Create a common model that you share with the people who build, support, and manage the technology.

People use the different types of documentation to different extents; when someone says that a particular technology “has good documentation”, they typically mean that it has the types of documentation they tend to lean on, presented in ways they find usable. When someone says that a particular technology “has bad documentation”, they either mean that the types of documentation they would like to see are missing, or they exist but are not to their liking.

This means it is possible for people to talk across purposes about the same collection of documentation, not seeing the other’s point of view because they get different things out of the documentation. So one person might think their project has great docs because they have a lot of fantastic how-to articles and reference, but another person wishes they would add conceptual guidance because they do not want to know how to complete a task, they want to think about how they might achieve any task.

Inside Macintosh, the official source of documentation for Mac software development in the classic era, caters to (almost) everyone. This being the De Programmatica Ipsum issue on file systems, I will dive into the Inside Macintosh: Files volume for a closer look. For those who are reading along at home, I am using the (printed and bound, thank you very much, by Addison-Wesley) edition that corresponds to version 7.0 of the Macintosh System.

The first chapter, Introduction to File Management, includes conceptual guidance (“About Files”), how-tos (in the section on “Using Files”), and reference (“File Management Reference”). There is even a sort of reference to the reference, in a pair of “Summary of File Management” sections at the end. One is the Pascal Summary and the other is the C Summary, and they are everything that a module interface or a header file would tell you about the constants and functions available.

Note: no tutorial content. If someone new to Macintosh wants to write software and never used random-access storage before, and does not know how an application might work with multiple files and what operations to expose in their UI, they are not learning that from Inside Macintosh: Files. In fact, they are not learning that from Inside Macintosh: Human Interface Guidelines either, which explains that File menu operations “pertain to housekeeping tasks for documents” and describes each of the common items in turn (in which we notice an inconsistency: the File > Close menu item does not pertain to housekeeping tasks for documents at all, it is a window management operation). This might seem like a weird niggle but it is not, it is a huge gap: the 1980s-1990s microcomputer platforms like the Macintosh, Amiga, Atari ST, or Archimedes were the first exposure many people had to graphical user interfaces with windows, icons, menus, and pointers, and simultaneously the first exposure many had to non-sequential storage. You have to remember that this was an era when broadcast TV included minutes-long segments describing how to use a mouse. it is entirely possible that someone wanted to write an application without understanding how a computer could find multiple files, or how a user might be expected to juggle multiple files, and without knowing how the New, Save, and Open actions interact.

If you do understand that, you will get a lot of nerdy details on the innards of the system! You learn about how the Hierarchical File System allocates storage blocks on the device to files; how it separates a file’s data from its resources using two forks (surely it should be one fork with two tines?); how catalog node IDs, B*-trees, directory records, and directory thread records all work together to organise the hierarchical structure of the storage. You could write your own implementation of HFS from scratch, but still not know how apps model documents as files. Anyone who lived through the various transitions in identifying files on the Mac—from file system specifications, to FSSpec records, to FSRef structures, to -[NSString filesystemRepresentation], to NSURL, to bookmarks—can relive that history if it is really what you want to do, by diving in to the documentation. Anyone who wants to know how Apple’s developers conceptualize files on the Macintosh, and how they think Apple’s users should work with files on the Macintosh, needs to fill in that gap themselves.

Nonetheless, I still think that Inside Macintosh is “good” documentation. That is mostly because I learned what the expectations for files, and random-access storage, were from other sources, so I do not need the tutorial content it lacks. Plenty of successful developers created applications for the Macintosh that used files in ways that people with Macs expected them to. But you have to wonder how many people who wanted to write Mac apps did not, because the Inside Macintosh documentation did not bootstrap their understanding of the inside of the Macintosh.

Cover photo by the author.

Back to top