Espinosa: When Steve hired me to put together the Macintosh documentation suite, he gave me a couple watchwords that completely changed the approach we took. First of all, I was hired to run pubs on Macintosh when the Macintosh group was only 6 or 7 people. It was fairly remarkable to get the Publications department in so early in the project. That's because Steve knew I had a lot of work to do in planning and figuring out what to write about. It wasn't just, "Here's the product, write about it." The second thing was that he really wanted to capture a value that he had captured osmotically from what people really valued from the Apple II: that with properly designed software, the system teaches you how to use it itself. If the menu structure and the purpose of the application and the user interface are clear enough, you don't need manuals.
So he told me that my job as publications manager on Macintosh was to put myself out of a job, in that in the best of all possible worlds, my job wouldn't need to exist, because the software would teach itself. And that was a real good lesson that a lot of people have forgotten: that the chief aspect of good user interface design is that people should be able to walk up to a system on their own, and figure out how to use it without having to read a book, or even having to read a help system. A help system is often not much better than a book, except you can't look at it and the system at the same time because you don't have the screen real estate. So I started hiring a bunch of people. I was only 20 years old, but Steve was 24, so he didn't consider this that unusual.
There were two major groups I worked with that got the publications process on Macintosh incredibly connected with the project as a whole. The first was with the software team. That started by doing tech documentation, and getting ourselves familiar with and well-connected with the programmers, by writing documentation by which they could get other people to write programs sitting on their operating system. I think that really really helped, because it proved to Jerome Coonen (Macintosh's software engineering manager) and Andy Hertzfeld and Steve Capps and everybody could trust me because we wrote the technical manuals that let people use their system software. You can't just publish APIs and hope people will understand how to do it: you need the low-level technical documentation to explain it. And when they started seeing these programs coming in from third parties that really used their software right, that helped confirm that the publications group was an integral part of the software design process.
Caroline Rose was just fiendish about that. She was our technical documentation lead, and her relationship with Andy was really, really funny. She was doing what I was talking about before, which was asking him the tough questions about what he was going to do next that he hadn't thought about before. She really made his life difficult, and helped him design better software. She would sit there and say, "But I don't understand. Tell me again how you build a control?" And he'd go through it over and over again, until he finally came to the realization that, "You know, if it's this hard to understand, I didn't do it right." And he'd tell her to go away, and then he'd completely reinvent it overnight. The next day he'd say, "Okay, this is how you do it now," and she'd say, "Oh, that's much clearer; thank you for explaining it."
Well, he didn't explain it better; he completely redesigned it, because it was so hard to explain. That is when documentation really works. And Caroline is the best I've ever seen at that. She sits in an engineer's office, and she-- she doesn't play stupid, she just asks them over and over and over again, to explain clearly what they mean. And it forces them to think clearly about what they're designing. She's just without peer.
But then I brought in my user documentation people. Lynnea Johnson did with Randy Wigginton on MacWrite what Caroline did with Andy and Steve Capps on the operating system. Lynnea had little if any formal experience as a technical writer, and she had little if any formal experience with computers. She didn't have very much experience working in business at all. She was working in the typing pool at Bechtel when I hired her. She had just come off of a three-year boat trip where she was part of a crew with rotating captainship; the ship just went around the world two or three times, and picked up cargo in one port and carried it to another, and that's how they got enough money to sustain themselves.
Those were her credentials to be a technical writer. I saw a writing sample and thought she had the right voice. I wasn't looking for-- in hiring for the Macintosh project we weren't looking for credential and experience, we were looking for people who were a good fit, and who got it. And she had the right writing voice, and she got it. And she just sat down with Randy Wigginton, and while trying to write about the user interface design of the rulers she'd say, "I can't explain this, it doesn't make sense." And then she and Randy would work out, well, what if you dragged the tab from over here, and it did this [motions with hands, as if dragging tabs].
So in those kinds of cases, the writing team that I hired and threw in with the programmers were really, really vital in designing the user interface. By being the people who had to explain it, they helped the programmers figure out how much better to do their work.
The anti-case of that were the interesting interactions between Bill Atkinson and Carol Kaehler. Carol had been in various places before. She'd done some technical writing at Xerox PARC, and she knew Bruce Horn from there. Her husband was Ted Kaehler, who worked with Alan Kay. She was writing the MacPaint manual, and Bill Atkinson had a different idea of how the MacPaint manual should be written. The other group I was working with-- and this fits in with the story-- was the creative services team. We had an incredible creative services team. It was first under James Farris and Tom Suiter, and then we hired our head of creative services for the Mac, and he put together a team under Clement Mok, who also later went on to do bigger and better things.
Steve's original idea for the manuals was that they would be like magazines. They'd be really readable, they'd be short articles, they'd be essays and things like that. The problem was that he didn't have a product to write about, and he we had all these traditional things we had to cover, like how to handle a floppy disk. So we worked and worked and worked with the graphic designers to come up with a book design that would both aesthetically and structurally serve our purposes-- what the typeface would be like, how the columns would be laid out.
We separated the book into three sections. First there was the tutorial, which would take you step-by-step through an introduction to the product so you'd get a feel for what it's about. The middle section was a cookbook, where each two-page spread, magazine-like, would be about a single task, like how to change margins, or how to copy a disk. It was originally designed with six columns, with substeps in the columns-- the idea being, you'd open to the page, put the page on the desk, and without having to flip through the pages you'd follow the steps and you'd be done. The third section would be a more traditional reference section where we just kind of walked through the product, menu by menu, function by function, and would explain what everything looked like and everything did. There would be callouts on the side with a handy tip, or something you may need to know, or here's a warning.
It was somewhat derivative of the book design for Lisa and Apple II, though the cookbook section was novel, and the writing style was a lot chattier. We also got to spend a lot more money on photography and printing on our technical manuals, because-- well, we worked for Steve. The expensive one was six-color process throughout. For the less expensive ones he demanded that we do black-and-white duotones, rather than just split screen for the photographs. It was lavish, it was very, very nice. Nobody ever got to spend that much money on manuals, but Steve wanted the whole effect to be crisp and professional and very high-quality.
So the process of actual writing went fairly smoothly. Once we had the structure, we put together the tutorial, and then we tested it: we ran people through the tutorial over and over again, and just watched people do it, and saw where people got it and where they botched it. That was a traditional technique and it worked very well. The cookbooks, the hard part was figuring out what tasks people would want to do, and then cramming it into the grid. The reference section was traditional. So we worked with the graphic artists to get the book design, and we worked with the programmers to get the content right.
The one outlier was Bill Atkinson, who thought that MacPaint needed to be different. Carol Kaehler had put together an alpha draft, a first draft, of the MacPaint manual, that was in our template: it had a longish tutorial, followed by a bunch of cookbook sections, and then it had a reference which led you through what the tools did, and what all the menu items were, step-by-step. Bill Atkinson thought that it was too big, too dry, too stupid, and too devoid of any kind of fun and exploration. We fought about it. I thought the books should be a suite, and they should have consistency, and continuity, and familiarity, and all the things we valued in the user interface. If you looked for a cookbook section in one manual, you should find a cookbook section in every manual; all of the great Macintosh values, that you should be consistent wherever possible, and maintain the graphic look.
But Bill's value was, MacPaint is different. And it was different: it took up the whole screen, you couldn't drag the window, you used the mouse in completely different ways. He, out of the goodness of his own heart, he and Susan Kare-- with a little help from Steve Capps and Rony Sebok and Andy Hertzfeld-- and not much discouragement from Jerome Coonen-- who knew how what they were doing would be received but just decided not to interfere-- one night when they should have been coding, stayed up all night and wrote a MacPaint manual that was the way they wanted it to be written. And they presented it to Carol with this look in their eyes saying, "We did this great thing for you: we saved you all this work by completely trashing everything you've spent the last 6 months on, and aren't you grateful for us helping you see the light on how your book should be written."
It was a challenging management moment. And because it was Bill Atkinson, after a couple long walks around the building and a couple of screaming fits with Steve, we just sat down and clenched our teeth and said, "Thank you, that's wonderful, we'll print just what you've written." And what came out what the MacPaint picture book. It delighted some and enraged others. And several years later, they wrote a real manual for MacPaint, because they had to. [Pang laughs]
So in the documentation process on Macintosh, we worked early and often with programmers, we started early on book design, and tried to keep a writing style that fit in with the whole character of the machine, and the character of the project as well: the sense of cohesiveness of the Macintosh team, and the fact that everybody got to work on and look at everybody else's process. Some of our best reviewers our books were people in Finance, who read our books voraciously. It was great having the Finance people review our books, and not for "This is going to cost too much to print," but "I don't understand how you do this in the word processor," because they were much more the target market than the programmers.