The next week I sat down to meet with Caroline for the first time, and she couldn’t have been more different than the previous writer. As soon as I began to explain the first routine, she started bombarding me with questions. She didn’t mind admitting it when she didn’t understand something, and she wouldn’t stop badgering me until she comprehended every nuance. She began to ask me questions that I didn’t know the answers to, like what happened when certain parameters were invalid. I had to keep the source code open on the screen of my Lisa when I met with her, so I could figure out the answers to her questions while she was there.
Pretty soon, I figured out that if Caroline had trouble understanding something, it probably meant that the design was flawed. On a number of occasions, I told her to come back tomorrow after she asked a penetrating question, and revised the API to fix the flaw that she had pointed out. I began to imagine her questions when I was coding something new, which made me work harder to get things clearer before I went over them with her.
Initially, we distributed the raw documentation to developers piecemeal, as it was written, but eventually we wanted to collect it into one definitive reference called “Inside Macintosh”.
I never heard of Caroline Rose until now, but as far as I am concerned she is an unsung hero in the history of Apple and should be a role model for tech writers everywhere.
You can get a PDF of the 1985 edition of Inside Macintosh here. Skimming through, I’m struck not only by the clarity and thoroughness of the writing, but its consistent tone. It’s technical but has a human touch that doesn’t feel forced or overly casual.