Caroline Rose on Documenting the Macintosh

Source: Interview with Caroline Rose, 14 March 2000.

Comparing the Mac Project

Pang: It sounds as if the experience of working on the technical documentation for the Macintosh was somewhat different from your previous work. Not only was the local culture or esprit de corps different, but the place that the documentation played in the life cycle of the machine was different. Is that the case?

Rose: Yes. Notably different. It was part of the design of the application programming interface, whereas at Tymshare -- which was much more traditional -- I was usually documenting things after they had already been created. That wasn't the case at Apple: I was there very early in the Mac group, because Chris understood that a good writer with a technical background can help shape a product -- in this case the API.

Chris Espinosa talks in his interview about Caroline Rose's work.

So I was constantly telling them, "This doesn't make any sense," or "The name of this routine doesn't match what it does." And it was very important, because different people were hired to do different things, and whether they got together with each other to talk about what they were doing was left up to chance in a lot of cases. But I got to see everything. So I would document the Window Manager, and then I'd document the Control Manager that another programmer was writing, and I'd see that there wasn't much consistency in what they were naming their routines, and in what the routines did, and I'd find bugs, and I'd write little programs. So I was helping to shape the product.

Jef Raskin talks in his interview about the role technical writing should have in product development.

And even the user interface -- I was a little involved in the documentation of it, and we would help shape the user interface as well. That was very different from anything I'd done at Tymshare.

But I loved that, and that's one of the things I loved about working on the Mac. These days, that's more common; but again, in the beginning of my career, my job was just a cut above secretarial. You could see that in salaries, in the way I was treated, where I was seated, in the perks and everything -- it was all very low. It got better and better, the more they took advantage of my skills and the skills of other writers, the more we were able to shape the product. That made it much more exciting than just being a scribe. I've never thought of it as just being a scribe.

Special Challenges

Pang: What special challenges did you face in writing documentation for the Macintosh, and what were their sources -- the machine's complexity, the need to produce documentation that would be especially attractive to developers or the public, etc.?

Rose: A big challenge for me with the developer docs was to keep up with documenting things as they were being developed. We were determined to have the developer docs ready early, so there wouldn't be much of a delay before the first third-party apps. Initially, we released Inside Macintosh one chapter at a time. The API was constantly undergoing change and refinement; as the engineers worked with the API, they'd make changes, and I'd also point out needed refinements. The revisions were constant; nothing was stable.

There was a lot of time pressure, which made it difficult to do things in orderly ways. (I agreed with the joke going around at the time: "What's the difference between the Mac group and the Boy Scouts of America?" "The Boy Scouts have adult supervision.") Genius and inspiration were valued much more than order and organization; I think chaos was more or less equated with genius. Certainly Steve operated in a chaotic manner, always changing his mind about things.

One big way in which the constant changes and the time pressure presented a challenge for me was that the original Inside Macintosh documentation lacked examples, which would have been very helpful, but there was absolutely no time to write them. Inside Macintosh took a beating for that reason for years, and it hurt me to hear that.

I was also involved in the user docs. The challenge there was to document applications with a graphical user interface for the first time. The first drafts of some docs (esp. MacPaint) were completely rewritten to incorporate heavy use of graphics. We were breaking new ground.

Structural Changes and Revisions

Pang: How much did the documentation you were writing change from start from finish? Did you have to make many changes, as programmers made changes, as Steve came in and decided he wanted something else?

Rose: Well, at first I thought you meant "How did the structure of it change?" Which isn't what you meant, but I do want to say this on that point: Chris had the idea that we had to get this documentation out really fast, so we did it a chapter at a time. We never looked at an overall structure of the whole thing, not until much later: we looked at the structure for a chapter. One of the things I suggested in the beginning, because I'm fanatical about this kind of thing, was to write a style guide explaining how we would organize the chapters.

We did a little polling of the programmers and came up with an idea -- but Apple stuck with it way too long. I think there was some inertia after I left. I would rather have stayed and figured out a better way to do things, but for various reasons, I left, and they stayed with that structure way too long. It worked when you had to get things out a chapter at a time, but when they were long past that point, they should have been looking at a different structure.

But to get to your question: The details changed constantly. Constantly. And fortunately, Chris set things up so that that was not a problem. When there were enough changes in the Window Manager, you'd go back to the Window Manager chapter, you'd update that, and send every interested developer the latest version. Of course, these days you'd just post it on the Web. We did the paper equivalent, and I think we did it pretty well. And I think that was radical at the time. People were used to putting out polished books, and we were putting out a chapter at a time. But it worked.

So there were a lot of changes, and there were a lot of drafts.

Pang: So were you getting feedback from developers about this process?

Rose: I'm sure there was, but I wasn't one of the people getting that feedback. You can't imagine -- there was so much going on. You cannot imagine the pressure. You've heard about the 90-hour weeks; I wasn't working 90 hours a week -- that style has never worked for me -- but a lot of people were, and I don't know how much time anyone had to consider developer feedback. They themselves were using what we were writing, so they got a lot internal feedback, but I don't know first-hand how much came from the outside world. Probably there was some direct contact, because there wasn't much bureaucracy then; but we were too busy to pay much attention to them. Maybe Marketing did.

Horse of a Different Color

Pang: One of the sections of Inside Macintosh is "A Horse of a Different Color," in which you explain how things didn't work the way programmers would expect. Could you expand on what those differences were?

Rose: There was one big difference: and that was that things didn't happen in an order you could predict any more. You couldn't -- as in the old days -- just say "Give me this information, and then this," and then say, "Here are your results." That's what programs used to be like. Now, an application was something that sat there and waited for the user to say what he or she wanted to do, and you didn't know what that was going to be. So you had to poll for these events from the user, and then decide what to do accordingly. And that was completely different.

That was the big change -- the event loop, literally looping, waiting for the next event to come in, and deciding what to do next. So you had to keep track of the state of things very well, not knowing what was going to happen next. It seemed very chaotic at first, to me and to a lot of other programmers: they'd wonder, "What is this? What is an event? What's the context, what's the order?" They just didn't have the right mind-set. Once they got that, and saw how simple it was, then a program's a program; it's all just ones and zeros at the bottom. But that was the problem, the event loop. That was the worst.