The Confabulator Cafe

Tag: technical writing

  • It’s All About Storytelling (Again)

    Humans are a storytelling species. Stories are how we make sense of the world. Stories turn raw data into intelligence. We cannot make decisions without telling ourselves what stories we would like to make true.

    My federal counterparts hire contractors to do the information collection and repackaging work that I do for the state. On occasion we share information on points of mutual interest, and I’ve seen some of these contractor-generated reports. And I gotta say, I’m much better at it than the feds are.

    Why? Because I never forget that I’m telling a story [0].

    I have a template that I follow which uses your basic inverted pyramid structure. We begin with generalities: what is the issue and why do we care about it? I’ll introduce the stakeholders and run through the issue history from a couple of different angles, and the deeper I get into the document, my descriptions get more specific. I wrap up with conclusions and recommendations. Pretty basic, right? By the end you know the story– what is the problem, how did it get there, who is to blame, and where do we go from here. You probably learned this in English class.

    On the federal level, though, it’s all about getting paid, and they’re not ashamed of it. The first page of the document usually describes the contract, and every section thereafter is in contract order [1]. The document is specifically designed so that you can lay it on the table side-by-side with the contract and check off that every contractual obligation has been satisfied, in order. Good job, well done, you’ll have a check in 30 days.

    The contractors work hard. They use the same resources I do, mostly, and collect the same data. They are without a doubt dedicated and passionate about their work. But the structure of the contract precludes their ability to tell the story, and they write a report as a series of unconnected collections of data. They never even see the story, which means they can’t identify and fill plot holes, they never ask, “What if?” and they end up missing out on critical insights and promising lines of inquiry.

    I feel sorry for the federal project managers who have to read the reports and try to make decisions based on them. All the information is there, but the serious skull work of making sense of it all is yet to be done. One of the reasons I am careful to tell stories is because I know my bosses are busy people. They don’t have the time or the attention span to do a lot of synthesis. I have to lay it out in plain language, and the best way I know to do that is to tell a story.

    [0] It’s a factual story, and every point in it has to be backed up in reality somewhere, which often means a six-page memo has 200 pages of attachments.
    [1] Which would be fine if whoever wrote the contract knew how to structure a story. But they don’t.

  • Boring But Necessary: My Nonfiction Life

    I’ve already got a whole lot of nonfiction in my life, but none of it’s the fun kind.

    I am a freelance technical writer by trade, and depending on whether I’m in the feast or famine portion of my employment cycle, I spend large portions of my days working on behalf of companies that build cell phone towers. It involves a lot of research and letter writing and watching the calendar to see if anyone has gone beyond their FCC-mandated response times.

    Roughly 90 days after I’ve been assigned a project, I get to cobble together a report that either says “Go for it. No one cares if you build it there” or “Run, don’t walk, from this location. Do it! Do it now!”

    Whoever coined the phrase “thrill a minute” obviously had this very specific profession in mind.

    (more…)

  • Becoming Technical

    It’s hard to say how, exactly, my writing has changed in the past year. Most of the writing I’ve done has been in new, uncharted territory. This past year I put a pause on creating new content and instead have been working on editing my novel, writing blog posts, and buying guides. So, I suppose, if I were to judge how my writing has evolved, I’d have to say it became a lot more technical in nature.

    I’ve learned how to write to fit somebody else’s guidelines. Or rather, I’ve honed that skill from when I was a college student. I’ve learned how to research. I’ve learned that I can only write so many technical articles before I’m ready to snap and give up on writing altogether. I learned from that lesson and resigned from my second job before I did something drastic, because let’s face it, writing is just too much fun to give up on. (more…)

  • I Have Nothing To Fear From Maternal Attention

    My mom taught me to be a technical writer.

    It was my first job out of college. Her company needed to hire an hourly “contract” worker (temp, no benefits) to read 20,000 lines of Fortran code and describe them in English. My degree was in the sciences, and I had taken exactly one programming course and no writing courses whatsoever. I had no idea what I was getting into.

    The pay was just OK and it was an hour commute each way, and despite the fact that our workspace was five people crammed into a 30 by 40 foot offsite “office” I was still expected to wear pantyhose. It was the early 1990s and we were working on, I think, two Macintosh LCs [0] with these nifty 8.5 by 11 inch monitors that you could rotate on the fly to either portrait or landscape orientation. Adobe was the undisputed king of desktop publishing in those days and we produced seven books in Pagemaker, ginning up flowcharts and other line-drawings in Freehand. I thought our setup was the neatest thing in the world, going as I was from typing term papers in WordPerfect 5.1 [1] and sneaking into an unused lab in the biology building to run off free printouts on a University dot matrix printer [2] to WYSIWYG layout design and laser printing. (more…)

  • Why I Write

    Because I’m paid for it. In a career that has spanned multiple mighty professions, writing has always turned out to be my most salable skill.

    I work in a space that librarians and search algorithm authors call the Long Tail of Information. Think of it this way— a little bit of information is important to vast quantities of people. How to eat properly. The date of the next general election. The price of tickets to The Dark Knight Rises. After that the graph tapers off pretty sharply. The vast majority of information out there has a very small, but very enthusiastic, audience.

    When I write a report, I’m pulling together data from various sources, online and offline, and repackaging it into a product that is of vital personal importance to anywhere from, say, five to thirty-five people. It may be of casual interest to a couple of dozen or a couple of hundred more. And it will have absolutely no impact on the lives of the other seven and a half billion people on the planet.

    None of this means that this information isn’t valuable! People will use it to make important decisions. Somebody could end up spending a million dollars. Somebody else might or might not get sick. The collective IQ of the planet will increase by an infinitesimal amount. Work will get done. People will get paid.

    And I’m one of them.

  • Sometimes Complexity is Not Your Friend

    In technical writing you want to avoid writing complexity. Narratives should be as clean and straightforward as possible, without leaving out any important information. Clean and straightforward is particularly important when addressing complicated topics.

    Think how a reader approaches a manual or a report. A very few will read it from front to back. The rest will scan it, trying to pick out needed information without necessarily committing to an in-depth study. This presents particular challenges to document design.

    Because I cannot count on my readers going straight from A to B to C, I find it works well to divide information into chunks. Ideally there will be no more than one fact per sentence, one full idea per paragraph, and once concept per page, or two-page layout, if it needs more room. Supplementary information such as definitions, explanations, and examples can be placed in call-out boxes or sidebars, visually separating them from the rest of the page.

    By chunking information into page-sized pieces, the user can review exactly what they need to know without flipping back and forth (or in the case of screens, scrolling). This also forces me to concentrate on the meat of my presentation, leaving out the clutter of extraneous detail (think of the call-out box as the plastic storage bin of information design).

    I also have to consider document navigation. There should be descriptive headings and subheadings, of course. The table of contents should be comprehensive and reflect the structure of the document. An index must, above all things, be useful. I’ve seen computer-generated indexes that cross-reference every noun in the document, without any indication as to which are the important ones. If necessary, add a glossary of definitions, and if your document is acronym-heavy, a separate list of acronyms and their definitions.

    If your document describes a sequence of actions, such as how to set up a laser-cannon emplacement (first, check area for Ewoks) or how to run a political campaign (first, check constituents for Ewoks), “breadcrumbs” are handy. Breadcrumbs are a visual cue that lets the reader know where they are in the sequence. When the reader is trying to look something up later, they may remember that the information was in the green-tabbed section, or somewhere after Step 2 but before the chafing dishes are removed from the buffet.

    It can be useful to add cross-references when necessary. Don’t feel at all shy about mentioning that the discussion of optimizing pixel size is on page 3-11, and the complete technical specifications of the Wonkaville Golden Ticket are included in Attachment F.

    And lastly, beta readers. One difficulty with technical writing is that the writer has to be come temporarily an expert in the topic, and it’s easy to get lost in the weeds. A fresh beginner’s eye is the only way to identify critical gaps in logic or presentation. I usually tell my beta readers, “Tell me where it sucks, tell me where it’s confusing, tell me what you don’t understand.”

  • Establishing Trust

    In technical writing, there is really only one useful point of view, that of Godlike Omniscience. The tech writer’s challenge is to present information that can be complicated, confusing, incomplete, and flat-out tedious to the reader in a way that supports decision making. Furthermore, the information has to be structured in a way that makes sense the first time it is read, but also allows the reader to go back and easily reference key points.

    You can’t achieve a level of trust with your reader unless you speak with a voice of authority. This is no time to play games for the sake of artistry. Simple, direct, I-know-what-I’m-talking-about language is what is needed.

  • It’s the Data, Stupid!

    The coolest thing about being a non-fiction writer is all the research I get to do. I love being a lifetime learner; it’s like I’m getting paid to grow a little smarter every day.

    When I’ve done my research, when I’m confident of my facts and my references, and the story has revealed itself to me, the words come easy. If they come grudgingly, or not at all, it’s a signal that I have to go back to the library, or the museum, or archives, and figure out the missing pieces. My notes are sprinkled with questions I need to find answers to: What if this were the case? What would account for the timing here? What did these people do, and how did they do it, and would they have done it under these particular circumstances, and most importantly, how can I figure out what those circumstances were? It’s like detective work, only without the dead bodies and wisecracking medical examiners.

    It’s storytelling about what is, not about what should be, and that’s a powerful thing.

  • On Building Trust With Your Words.

    All week we here at the Cafe have been discussing how to reveal character through language. Put yourself in the reader’s mind. What should the reader be told, what should the reader be allowed to infer, and what should the reader be assumed to know? A technical writer must also ask those questions, not to illuminate character, but to convey factual information.

    It comes down to trust, really, between reader and writer. You, as a writer, must create a space with your words in which trust can grow, in which the reader feels free to say to themselves, “I don’t know where this is going, but I’ll be glad to get there.” It’s a difficult challenge, and an awesome responsibility.

    The vast majority of the documents produced by my bureau are written by our techies for the benefit of other techies. It is presumed that the reader has, or can easily obtain, the necessary context to make sense of the information. For most ordinary purposes, that is true. We don’t need to explain every measurement, spell out every acronym (more than once), or describe the significance of the data. To do so would be patronizing and could actually damage the writer’s credibility.

    However…

    Some of our documents, arguably the most important ones, are not written for techies. They are written for the general public, or legislators, or for other members of our agency whose technical expertise lies in other areas. For these audiences, we must provide the context as elegantly and concisely as possible. We must educate them without either talking down to them or confusing them. Failure to do so can result in a loss of credibility for the entire agency, or worse, loss of funding.

    It’s not easy, building a trust relationship with someone you’ve never met, may never meet, and who may not even exist. Unlike bloggers, journalists, or novelists, it’s rare for a technical writer to develop a following, and for credibility to accrete to the byline. The relationship has to be established anew with each document. The stuff I write becomes part of the state’s permanent record [0], and it has to be right, first time, every time.

    [0] I wonder if this is what my teachers meant when they said, “This is going on your permanent record?”

  • On Setting the “Scene” in Technical Writing

    All writing is persuasive writing—first you must persuade the reader to keep reading, if for no other reason than to justify your labor. You must persuade those who paid for your work that their money has not been wasted, and you must persuade your inevitable critics that you have sufficient credibility to make your argument. A fiction writer might have five pages to make their case. A technical writer is lucky to have five paragraphs to cover the same territory; more likely, five sentences. Nobody is reading your work for fun, so you have to set your scene quickly, directly, and elegantly.

    Who, what, when, where, why, and how? Who is involved, what is the situation, when did it start, where can it be found, why do we care, and how bad is it? There are potentially carcinogenic fracking chemicals in drinking water in Pennsylvania. The city council needs to know more about backyard chicken raising before changing an ordinance. Congratulations, you have just purchased our software! In the case of Smith vs. Jones, the defendant requests a dismissal on the grounds that the plaintiff has not suffered damages. When in the course of human events, it becomes necessary for one people to dissolve the political bands which have connected them with another, … a decent respect to the opinions of mankind requires that they should declare the causes which impel them to the separation.

    As far as the mechanics goes, just say it straight out, using clear, direct language that commands the reader’s assent. Don’t imply, don’t infer, don’t force the reader to come to their own conclusions. Imagine that they are busy people who want to be told what to think, preferably somewhere on the first page.

    Note: this is for non-fiction writing. In fiction, half the fun is in implying things. However, setting up a red herring in a policy document? Ninety percent of your audience will come to the wrong conclusion.