One of the things that’s so admirable—and inimitable—about Ernest Hemingway is that he leaves out a lot of information. He doesn’t tell us where we are or what the characters have to do with one another. He doesn’t tell us how tortured the histories are of his characters and he doesn’t even tell us why these people are together. He leaves us to figure it out for ourselves; we can decide how much information we need and make up what Hemingway doesn’t supply.
But that doesn’t work very well in technical writing.
If you want readers to follow along in an example, you have to tell them where the example is placed. Is it a UI window, and if so, what is the menu path? Is it a bit of code to type? If so, where do we enter it (what application, what view, what language, what process, in the middle of what other chunk of code)? Is it a theoretical discussion? If so, what building blocks do we have to hold on to so that the discussion makes sense.
What if I wrote:
Line 11 defines a collection of contacts for the Contacts field, and line 12 defines a collection of string elements for the PhoneNumber field.
Here are some assumptions we can make:
Here are some things we can’t assume:
You can see that the assumptions that we can make are not that helpful. The assumptions that we can’t make are the ones that prevent us from following along.