Inside Macintosh – an exemplar of good technical documentation

Caroline Rose created some of the best technical documentation ever with the Inside Macintosh volumes. The Macintosh, like the Lisa, had a radically different programming architecture – it was event-driven rather than structured or procedural. And so, the documentation had to not just describe the Macintosh APIs, but also to put them in context so that people could make the shift. It didn’t try to teach event-driven programming, but it did constantly talk about how various parts of the system should be used.

PDFs of the original three volumes are online here:

http://www.weihenstephan.org/~michaste/pagetable/mac/Inside_Macintosh.pdf

It’s worth looking at if you are writing technical documentation of your own. You could go far worse than to try to emulate this style.

And to put the size of the documentation in context – there was 64KB of ROM, and 128KB of RAM, in the first Mac that shipped, and this was covered with about 1200 pages of documentation. For a modern system that encompasses millions of lines of code – either we write code much less tightly than Apple did back in 1984, or we don’t document it nearly well enough.

Oh, and I say Caroline Rose, because my understanding is that she wrote a lot of the first three volumes of Inside Macintosh, and even had an impact on the software by trying to document it (“Her systematic approach to clarity also helped internal Apple developers who, thanks to Caroline remarks, sometimes rewrote their software improving it substantially”). Here are some links:

 

Leave a Reply

Your email address will not be published. Required fields are marked *

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>