The beginning of your book is the hardest part.

I’ve written a lot of books on computer programming and so I try to get to the point quickly.

And yet…

I start to explain something and I think to myself, “before I talk about this, I need to explain that.”

So, for example, in my book on Objective-C if I want to send a message to a view to set its background color to red I would issue this command.

myView.backgroundColor = [UIColor redColor];

And then I panic.

I’ve used a dot on the left side of the equals sign. I probably should explain properties and dot notation and getters and setters first. On the right side there are square brackets. I should probably explain the syntax for message sending in Objective-C and show how to include parameters.

Maybe I should combine those two explanations and rewrite the command like this.

[myView setBackgroundColor:[UIColor redColor]];

Now I have to explain why the two are equivalent and why I prefer the first version to the second. Oh and then I probably need to explain the difference between class methods and instance methods and point out that “redColor” is a class method. Oh then I may need to talk about the memory model as I’m creating a new color using a class method so the reference count is increased by one.

Stop.

Take a breath.

You think you have a ton of things to explain just in order to put a single line of code in your book. You do have to explain it all—just not yet. You don’t have to explain everything before you display that line of code. In fact, you don’t want to.

The worst thing you can do is explain a lot of things before your readers care about them. They don’t pay attention to what you’re saying and they start skipping through parts and they may skip the important stuff while they’re nodding off to the boring, unmotivated stuff.

So start again. When I told you that I am sending a message to a view to set its background color to red, you probably were able to look at the following and figure out roughly that that was what this code did.

myView.backgroundColor = [UIColor redColor];

In other words, I provided enough context for you to follow along and now that you’ve seen the code I can start to explain the pieces you need to understand further in a way that involves you and makes sense to you.

In every book or article we write we get that panicky feeling that first the reader “needs to know” something. It’s true that if we were writing a rigorous argument we would need to build the foundation before revealing the conclusion. That’s not what we’re doing. We’re engaging the reader the same way a mystery writer does. We give them just enough context, we reveal the body, then we bring in the detective to explain what these clues around the body mean. We are very careful about the order in which we reveal clues and who we have reveal them.

We carefully consider what our readers need to know and when and we keep as little between them and the good parts as we need to. We make them want us to explain these details about properties and class methods. We don’t burden them with this explanation before they’re ready for it.

You’re operating a crime scene and vending out information on a need-to-know basis.