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