Inside Macintosh

What Hacker News says

1. StratoscopeNov 2022
   I see that my citation of that joke was not to your taste. I appreciate the feedback.

   HN provides a solution for the long cascading joke thread. To the right of every comment is a [-] link which collapses the entire thread.

   Have you watched The Marvelous Mrs. Maisel? I recommend it. There are so many scenes where she or another comedian just bombs. That is part of the life of a comedian, and learning from when you bombed is how you get better at your craft.

   Regarding the off by one joke, personally I find it insightful and relevant to the life of a software engineer. Doesn't it get you thinking about all the ways an off by one error can sneak into your code?

   Consider your everyday ruler or tape measure. What is the first whole number you see on it? 1, of course. But the ruler doesn't actually start at 1. It starts at 0.

   Or consider a graphic system where you describe the coordinates of a rectangle. You may describe these as (left,top)-(right,bottom), or in other words (x1,y1)-(x2,y2).

   Now how do you describe a single pixel? Is it (0,0)-(0,0)? That kind of makes sense. Or should you use (0,0)-(1,1) for a single pixel, and (0,0)-(0,0) is an empty rectangle?

   These are not easy questions to answer. One of the best explanations I've seen was in Inside Macintosh, written by my friend Caroline Rose.

   Here is a discussion with Guido's and Caroline's thoughts on zeroes and ones:

   https://news.ycombinator.com/item?id=6602497

   Let me leave you with an Amicus Curiae brief filed before the US Supreme Court:

   https://www.supremecourt.gov/DocketPDF/22/22-293/242596/2022... [PDF]

   The brief begins:

   > The Onion is the world’s leading news publication, offering highly acclaimed, universally revered coverage of breaking national, international, and local news events. Rising from its humble beginnings as a print newspaper in 1756, The Onion now enjoys a daily readership of 4.3 trillion and has grown into the single most powerful and influential organization in human history.

   Show morethread
2. msephtonJan 2025
   Caroline Rose was a technical writer at Apple from 1982, lead writer and editor of "Inside Macintosh". Apple-era stars at 1h22m in the video.
   thread
3. msephtonJan 2025
   Caroline Rose was a technical writer at Apple from 1982, lead writer and editor of "Inside Macintosh". Apple-era starts at 1h22m in the video, NeXT-era at 1h58m.
   thread
4. WillAdamsJan 2025
   Be sure to check out her stories on Folkore.org:

   https://www.folklore.org/0-index.html?author=Caroline+Rose

   and esp.:

   https://www.folklore.org/Inside_Macintosh.html

   thread
5. mananaysiempreDec 2023
   Compare[1]:

   > Pretty soon, I figured out that if Caroline [Rose, the author of the original edition of Inside Macintosh] had trouble understanding something, it probably meant that the design was flawed.

   [1] https://www.folklore.org/Inside_Macintosh.html

   thread
6. StratoscopeJan 2020
   > ...any tech writer working on developer documentation should be able to code/build/perform/use whatever task or api they're documenting without the help of an engineer. They should be able to read and understand code, and they should be willing to do so, even more so than the average engineer using some library code. They should be capable of understanding a library deeply and synthesizing and summarizing that understanding for users of the library.

   This is what made my friend Caroline Rose such a great technical writer. She not only can explain things in clear and simple terms, but she was also an accomplished programmer before branching into technical writing.

   Here is a story about the documentation that became Inside Macintosh:

   > 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.

   https://www.folklore.org/StoryView.py?story=Inside_Macintosh...

   One of my favorite examples from _Inside Macintosh_ is the discussion about the mathematical foundation of QuickDraw. Modern graphic programmers all know that a (0,0,0,0) rectangle is an empty rectangle. But why is that? Why isn't it a single pixel?

   The explanation on pages I-138 through I-141 is what made this concept make sense to me. Here's a PDF of _Inside Macintosh_:

   http://www.weihenstephan.org/~michaste/pagetable/mac/Inside_...

   Besides that section, there are all kinds of examples of how to explain a complicated concept in simple and understandable terms. It's worth a quick skim of the entire book to see what good documentation looks like.

   Show morethread