Chris Espinosa on Technical Writing

Source: Interview with Chris Espinosa, 13 June 2000.

Getting into Technical Writing

Pang: How did you become interested in and start working on technical documentation? How did you start doing it for Apple?

Espinosa: I was always a writer. I was always able to write and write well. It was one of my chief talents in high school and college. If a class required an essay, and a lot of the grade was based on writing, I would get a good grade in that class; if it required actual knowledge of anything-- like calculus-- I really did poorly. But through elementary school, junior high school, and high school, I wrote very, very well. I enjoyed writing, I enjoyed reading, I enjoyed putting together good sentences, I enjoyed having people read what I wrote.

Demo Time

My first job working at Apple was doing testing of the Integer BASIC that went into the Apple II ROM, in December 1976. Then, I wrote some demonstration programs. Mainly what I was doing in 1977 was writing demo programs, and doing demonstrations. People had this misconception that Apple Computer, at 20863 Stevens Creek Boulevard, Suite 3-C, was a real company, and that they could come and be greeted by a receptionist, and a sales representative might talk to them, and there would be a showroom where they could see machines. Instead, they'd walk into something that was a cross between the Bronx Zoo and the New York Stock Exchange. It was just incredible activity all the time, with people-- customers, vendors, venture capitalists, engineers, Mike Markkula, Steve Jobs, Regis McKenna-- running around all the time, very few set schedules, no meeting rooms. It was basically one big space, with carpet on one half and linoleum on the other half. On the carpet were half a dozen desks, for Sales, Marketing, and Administration. On the linoleum half, there were six lab benches, and that was Engineering and Manufacturing.

So when people read about us in magazines, or got our product brochure, or saw our advertisement, and were in the area, they would come over. They would open the door, and say, "I'd like to see a demonstration of your product." And there was just no way that the full-time personnel could handle that. So my job through most of the school year was to run demo time, every Tuesday and Thursday afternoon at 3:30. It was at 3:30 because that's when I got out of class. Demo time consisted of me, running the machine through its paces on a table, for whoever happened to stop by.

So I wrote demos, I did demos. I was, and continue to be, an extremely mediocre computer programmer. I took computer science in college-- this was before C. I do code now, and I really, really enjoy it; but I've found that the way to get good products out the door is to hire people who are much, much better than me, because I'm very pedestrian in the way I write code. But I enjoyed-- and this is perverse-- I found that I enjoyed documenting my code more than I enjoyed writing it. I enjoyed explaining to other people how it works. One of the first pieces of documentation I wrote was an explication of how Steve Wozniak's "Breakout" game worked-- line by line, in BASIC. That later was part of the Red Manual. When we hired Jef Raskin, he saw what I had been writing in terms of demo programs, and my documentation, and he said, "This person should be writing documentation, not software!" So he set me on writing some of the documentation for some of the early software packages that went out in 1977 and 1978.

Basically, I taught myself computer documentation. I had read a lot of documentation, everything from high-level software documentation to chip manuals, so I knew for myself what was good and what wasn't good, and made up the rest as I went along. And then we had some very, very good people who were hired at Apple: Phyllis Cole, who ran the pubs department for a while, Carole Cook and Steve Chernicoff, who had formal training in technical writing and were my editors. A writer always learns more from his editor than from anyone else, and Chernicoff edited me viciously: I would get back entire pages that were more green than black. That was how I really learned to be a writer. Just seeing that if I write it better the first time, I don't have to revise it as often-- the old lesson I learned in high school.

That was really how I became a technical writer. From technical writing I moved into technical writing management, and managed the Macintosh group technical writing. I hired people, I worked for Mike Murray, who was the director or marketing for the Macintosh, and learned a lot about marketing. Then, in the big reorganization of 1986, I became a product marketing manger, and spent ten years in product marketing, until I moved back into engineering. So basically, I've done documentation, marketing, and engineering.

Early Hiring

Pang: When you get started in documentation, Apple is still quite small place, and still managed pretty seat-of-the-pants--

Espinosa: If you had pants, yes. [Hands over Apple employee card]

Pang: Employee number 8. [Hands it back] Was there special status associated with being number 6, versus 9, versus 12--

Sandy Miranda (employee number 998) also fields this question in her interview.

Espinosa: The only status issues were the legendary-- and I cannot vouch for its accuracy-- 0, 1, 2 debate between Woz and Jobs. The reason I'm number 8 is that Mike Scott wanted number 8; everybody else just drew what they got. 1 and 2, or 0 and 1 with 2 missing, were Woz and Jobs; Mike Markkula was 3, Bill Fernandez was 4, Rod Holt was 5, Randy Wigginton was 6, Mike Scott was 7, I was 8, I think Dan Kottke was 9. I knew who the first ten were, in order, but no one really paid attention to it after that. Today, the single digit badge gets me status because all the other badges are five digits! [Pang laughs]

I remember that for a long time we had a great Marketing gadfly who was the voice of Apple-- he did great demos-- and he made a big deal of having badge number 36. So there was a time when it conferred some status, but it wasn't like New Hampshire license plates or anything [the subject of a New Yorker article that week].

The Challenge of Documentation

Pang: I want to understand where documentation existed in the development process. My sense is that at much larger places like H-P, most documentation was on finished products, but at Apple you were more intimately involved in development.

Espinosa: From Apple's foundings to the Lisa and Macintosh project-- they had a different attitude, a different philosophy, on those projects that Apple II and Apple III-- documentation was the poor stepchild. Not as poor as testing, but documentation tended to be what you did after the fact. Programmers never had enough time to explain to a writer what they had done, so documentation was almost an effort in investigative journalism: you really had to get in an figure out for yourself what the thing, rather than just writing down what the programmers told you.

You always were stuck in this classic conundrum. You had to be in the box with the product. The product was going to be done immediately before it shipped, because they sent the disks to dupe as soon as the bits stopped quivering. But the manuals had 6-week lead time. So there's this problem in that you have to as a writer, write accurately about what the product is 6 weeks before it's complete. So there was always a history of addenda and errata which were mainly things that changed after the manual was put to bed.

Documentation was always pretty much a contentious process. Programmers didn't have time to talk to documentation people because they were too busy writing code. They often didn't want to have to explain how their code worked: sometimes they didn't know how it worked, or they were being asked painful questions about what they were about to do before they had figured it out. It's really irritating having to talk to a writer who has this deadline who needs to know how you're going to implement something when you haven't written a spec, you don't know how you're going to do it, and you've got four other things to do now.

And then of course there's the controversy over the engineers reading your work and disagreeing with your writing style, or the order in which you're presenting things. As the most seasoned professional technical writers got in with a more school-learned, pedagogical approach to how they should present information, or we're trying to structure this in a template, and the programmers say, "But my program doesn't fit in that template! You have to write my manual special!"

Being a technical writer had its problems. Often the information you needed didn't exist. When it did exist you had to find it out because nobody was going to tell you about it. What you were told was often lies, or fantasies. And when they reviewed your work, programmers would either disagree with your writing style, or took a personal dislike to what you were saying. Some engineers would review an entire manual, and only change grammar or word structure or spelling, and not make any factual corrections to it at all. That was extremely frustrating. Then, you were told that you had to be in the box, and be ready 6 weeks before the product; but you were functionally unimportant because the software is really what sells. Like I said before, this was at a time when manufacturers were trying to impute value to software through bulk. People didn't understand why they should pay $120 for a software program when the disk cost $2 to duplicate.

So the entire software industry was trying to add value to software through packaging, and having a thick book was one of the ways to do it. But on the other hand, they wanted to hold down the cost of good sold. So they didn't want you to write a thick book, they wanted a nice thin book. But they also didn't want to take the customer support calls. So they wanted you to write a thin, comprehensive book-- that's also on schedule. The box that writers were put into was really pretty small and pretty tight, and there was a high amount of tension.

Politics of Documentation Management

Phyllis Cole and Carole Cook and Nellie Connors, who were the three publications managers I worked for, did a really, really excellent job of navigating the political waters of assigning writers to jobs, and matching writers to projects, and joining the political battle and saying to programmers, "You don't have a spec? [Slams table] You don't get a book. You write a spec before you write the code, and you will get a book in the box on schedule. But if you're just going to make up the code as you go along, we can't write the book to get in the box."

There were other times when the pubs manager had to take the fall. I had to do that once with the LaserWriter. It was an open secret that the LaserWriter driver was not ready when we introduced the LaserWriter in January 1985. It wasn't ready, and it wasn't going to be ready any time in the near future. But we had this shipping schedule, because we had to ship it at the Annual Meeting, and we had the "Lemmings" commercial, and we were introducing the Macintosh Office, and the file server just plain didn't exist; the only things we had were the network and the laser printer, and the laser printer had to ship, had to ship, had to ship. And we all knew that the software wasn't ready. But Bob Belleville couldn't stand up and say to Steve Jobs, "We have failed, the software isn't ready." So it was just a kind of agreed-upon conspiracy, and me and Debi and Mike Murray just looked at each other, and I stood up and said, "I'm sorry, my manuals aren't ready, we can't ship." And it was true. But the reason the manuals were late was that we didn't have ANYTHING TO WRITE ABOUT! [Pang laughs] So I took the fall for that, but it was part of the politics of the pub manager's job.

Lisa Documentation

But the Macintosh-- I can't say a lot about Lisa; Nellie Connor did a very, very good job in putting together the Lisa group, which took a much more traditional approach to documentation. The Apple II documentation was very freewheeling: it was a loose and open writing style, very conversational, very chatty, and people really loved them. But with Lisa they were going for blue-haired secretaries, they were going for institutional sales, so they wanted a much more professional look. So they had professional page design, they got a lot better typesetting and layout, while all the Apple II manuals had been printed on a letter-quality printer with headings Lettrasetted in-- literally, rub-on type-- and that was our camera-ready copy.

Lisa manuals were professionally typeset, but there were complaints that they were obtuse, they were ponderous, they were too big, they didn't get to the point, they used too much technical language, and that was just one of many, many things about the Lisa project that Steve rebelled against. Basically, when Steve hired us to do the Mac, it was to do the anti-Lisa. There was a lot of pointing across the street and sniggling and laughing, and saying, "Don't be like those bozos over there," and their manuals took a lot of that abuse.


Document created on 6 July 2000;