In order to write unified prose, you need to know who will be reading your work. If you’re writing about technology, the options are quite varied.

Flavors of Readers

Developers have analyzed all the aspects of an application, perhaps taking it apart, perhaps deliberately breaking it. These people know as much about the applications they use as the people who wrote the application. They don’t need definitions unless you are using a controversial word or introducing a new feature. Developers don’t need much relief from the facts you expose. Build something with these readers, don’t be too chatty or personable, and don’t over illustrate. This audience just wants the facts. IT professionals have a large body of knowledge regarding specific sorts of applications. They have a high degree of focus on security issues and administrative tasks. IT professionals’ level of technical acumen is less than that of developers but greater than most power users. Write step lists to accomplish tasks, and provide lots of context for what you build in text. Interrupt lengthy textual descriptions with screen images and useful bulleted lists. (A useful bulleted list is one to which the reader will refer again later rather than a listing of interesting items.) Power users have explored most aspects of an application and are ready to do some light programming to customize for their own use. They feel confident about using all the features, but are not ready to build an application themselves. Write step lists to accomplish tasks and build customized features, but keep the lists short—no more than ten steps at a time. Interrupt text about every two pages with an image, a table, list, or note. You might get chatty with this audience, if that’s your style. Explain all but the most basic aspects of what you are trying to accomplish and pave the path for true development work. Users have worked with an application for a while and are ready to become power users. They have established patterns of usage with the application and want to examine productivity tools. These readers are easily intimidated by code, so limit exposure to snippets that can be copied verbatim. It’s important to keep the tone light; you are not introducing something difficult, just something new. Interrupt the text about every page and a half with images, tables, lists, or notes. Neophytes have never used the application before. They have waited a long time and are nervously taking the plunge. Explain every term and avoid jargon. Be as chatty and friendly as you can possibly be; make it seem fun and compelling. Illustrate absolutely everything with images. Keep step lists very short, just three or four steps at a time. Avoid lengthy text sections or tables laden with scary facts. Managers need surface-level coverage about deep-level topics. They need to know what an application or feature does, but not how it does it. They need to know about conflicts or requirements, and they need to have the benefits spelled out early and clearly. Use images to show a new feature or a familiar interface. Use lots of bulleted lists and comparison tables, knowing that these readers may skim your work and read only these lists, tables, and figure captions. Managers expect marketing copy, so use limited amounts of industry-wide jargon (if you must) and metaphors to help them understand the purpose of the product. Comparisons to other products should be kept to a minimum, but are possible. Keep your voice professional and serious and do not allow yourself to wander off topic.

Combining Flavors

For these blog entries, I think of a combination of people in my life: a developer client, an attorney friend, and a particular reader who has revealed his personality through his comments and his own website. The developer is very sharp but didn’t pay attention in English class. He picks up ideas very fast, studies them closely, asks brilliant questions, and then applies the answers in his work diligently. He also struggles with some very basic concepts, the kind of issues most native-English speakers do correctly without much thought. He is a fun guy to be around, so in addressing his needs, I keep my tone light and focused, addressing an intelligent, interested professional. Another person I keep in mind is not a technical person, but an attorney. She writes well, knows everything about anything, and is quick to show you her powerful brain in action. Keeping her in mind keeps me from getting too playful and from addressing beginning writers instead of serious, highly technical insiders. The third person I keep in mind is a reader who often comments on my blogs. He is an editor and a writer, and he is quick to point out when I disagree with a known source or when something I declare as fact is opinion. Keeping him in mind helps keep me honest. You should feel free to identify specific individuals if it helps you keep your audience focused, or come up with your own collective as I have done for these blogs. The important thing is to identify your audience before you write the first word. That way, you won’t have to spend a lot of time pulling out extraneous information or adding in words of comfort or encouragement to otherwise undiluted technical work.