Copyright 2020 Melanie Spiller. All rights reserved.
Leaving Things Out
MelanieSpiller and Coloratura Consulting
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:We are looking at some bit of code that defines properties and/or relationships.We are discussing a chunk of code that has twelve or more lines.There are contact phone numbers involved, so this is a business application of some sort or a very sophisticated home office.The audience is coders.Here are some things we can’t assume:The application under discussion, the coding language, and the type of application being built (if any)The skill level needed to follow this discussion (some subset of programmers or developers)The larger subject is that is under discussion (the application, developing some specific functionality, defining relationships in a relational database, types of entities, objects, properties, or methods, coding language in general, etc.)What happened in the code before lines 11 and 12 and what happens afterWhat the definition is for “collection” because one item (Contacts) seems to be a parent and the other (PhoneNumber) seems to be a childHow many other fields are available, are nested into these two, or need specific definitionsYou 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.