On the job, circa 2000Retirement Day, 31 December 2022
My father worked at many different jobs in his life. He wound up as a technical writer at Raytheon in the late 1960s and early 1970s, documenting the Hawk, Sparrow, and what became the Patriot missile systems. As it has transpired, I became a second-generation technical writer and spent a full, 40+ year working life almost exclusively in that field. I worked for ten companies with hundreds of writers, editors, artists, and production experts, and thousands of managers, developers, testers, product managers, and marketers. I know I wrote hundreds of full manuals and thousands of documents, because midway through I started keeping count. Whether owed to excellence or inertia, few can boast so much experience.
A lot changed during those 40 years. My first writing tool was a typewriter, and my first cubicle mate, an experienced writer, wrote his drafts out longhand, in pencil, on legal paper. The focus of documents was the text because the format was controlled by a production team and because anything non-textual was difficult and expensive to produce. The review, approval, and print production cycle took 13 weeks. For my last publication, I wrote it at home on a laptop; some colleagues worked half a world away and I never laid eyes on them; the source files were stored half a continent away; I was the writer, editor, artist, and production manager; the product manager complained when the review/approval/production cycle took more than a day; and the publication appeared simultaneously in application help, the company website as web pages, and print PDF. The scope of what we documented, how we documented it, the tools we used, and where we published, changed utterly.
But some principles that I was taught as an associate writer, and some things I learned along the way about working with information and people, remained true when I retired as a site manager for the writing team. Quite a few people have written textbooks on technical writing, but I haven’t seen one on how to be a technical writer—to do good work, to do it efficiently and effectively, and to be a good member of a work group. My plan here is to offer occasional series on things I’ve learned over the years that don’t appear in textbooks on technical writing but are still, in my opinion, valuable and important to know.
To declare my biases, almost everything I wrote as a technical writer was in the domain of computer software, and I wrote for end users, system administrators, operators, and architects. I will try to make my posts in this series as widely applicable as possible and to separate facts from my opinions. You can judge or yourself what, if anything, is useful and applicable. I’d love to hear your comments as well.
Here’s a brief message, with an action, sent by a former STC officer who’s working on the bankruptcy filing. Please forward this information to colleagues who were members when the organization ceased operations.
Urgent: Ensure Your STC Membership is Included in Bankruptcy Filing May 16, 2025
What’s happening: We’re finalizing STC’s bankruptcy filing, but we hit a snag.
Why it matters: Without complete records, we can’t ensure your membership fees are included in the filing for potential refunds. The courts require full names and physical addresses.
What you can do: Please send the following information to Danielle.Villegas@stc.org by 31 May 2025: ✅ Full legal name ✅ Street address ✅ STC membership number (if available, optional)
Thank you for your prompt attention to this matter.
Best regards, Danielle Villegas Former STC Board Vice-President
After my suboptimal eyesight dashed my hopes of becoming a pilot, my fallback dream was to become a writer. My teachers praised my writing, but a good teacher encourages anyway; more tellingly, my grades were excellent, which carried more weight. I’ve lived the dream, enjoying a long, successful, and lucrative career as a technical writer. (Even among writers, the percentage of people who’ve made a living at it is very low!) But always in the back of my mind I wanted to write for myself. For the last decade of my working life I joked that someday I would write using adjectives and adverbs, semicolons and dashes. Now, in retirement, I’m free to do so. I want to offer some observations on how the art and science of technical writing compares to the art and craft of fiction writing: what’s the same and what’s different.
At this point in my fiction-writing apprenticeship I estimate I’ve written 200,000 words and at least 20,000 sentences (dialog lowers the average sentence length), but I waited to write this blog post until I could claim credible success writing fiction. I now have a smidgeon. (Yay!) You can find outstanding writers and teachers offering practical advice—successful former tech writers Robert Pirsig, Amy Tan, and Ted Chiang included—with far more experience writing fiction, so don’t weight my opinions heavily. Still, I know the “before” state of the transition as well as anyone.
By the way, some of what I’m passing on I learned from various courses offered by The Great Courses (formerly The Teaching Company). They are college-level courses without tests or homework, and I recommend them all.
What’s the same?
We know about the historical trend from the flowery and ornate prose of the eighteenth and nineteenth centuries, meant to set a leisurely pace, entertain readers, and show off the writer’s skill, to the short, punchy sentences of the twentieth and twenty-first centuries, meant to set a brisk pace, appeal to readers with short attention spans, and remove the writer from the narrative. We have the rise of journalistic style and the disillusionment of World War I, which created Hemingway, Dashiell Hammett, and others, to thank for the transformation, but over the last century the trend has only accelerated. Epistolary novels were invented in the 1600s, but today short stories have been written entirely in tweets.
Today’s fiction is created in a wide range of styles, but editors of commercial fiction push toward the same degree of concision that I was taught as a technical writer. I’m finding that beyond editing out clichés and stereotypes, achieving concision is a slow process of distillation, like turning grapes into brandy. The best sentences emerge from their predecessors, one at a time, sometimes a word at a time, often when I’m not writing. (The worst possible tech writer would be Oscar Wilde, who once said he’d “spent most of the day putting in a comma and the rest of the day taking it out.” I’m not that indolent, but I’m slow.)
At my first technical writing job, the stiff and formal house style was simplified and made more direct over the years. An oft-cited example I remember, the standard introduction to a procedure, was successively honed down one word at a time:
The operator performs the following steps: The operator performs the following: The operator performs: The operator: You:
In current practice, this procedural signifier is often completely omitted (which I consider going too far). Similarly, at one point at another company we actually wrote steps like “move the mouse cursor to the OK button and click on it,” which today boils down to, “Click OK,” and sometimes is skipped altogether (which again I object to, but whatever).
The common ancestor of both technical writing and fiction writing advice is Strunk & White’s The Elements of Style, which above all counsels writers to “omit needless words.” After saying for years that I was going to write long, lovely sentences using adjectives and adverbs, imagine my chagrin—yes, I say, chagrin!—when the first editing course I took (“Effective Editing“) advised writers to avoid passive voice, lengthy sentences, and adjectives and adverbs and write instead using active voice, vigorous sentences, and precise nouns and strong verbs to indicate action and mood—just what every style guide demanded. For both technical and contemporary, commercial fiction writing, the process is not one of elaboration, but of honing.
For example, in a scene set at a lavish company Christmas party, I wanted to describe what two minor characters wore. I imagined one dressed as a Southern belle with white lace gloves and her date dressed vaguely like Rhett Butler. After I wrote that (always after…), I thought I could do better and searched for images of the famous “Gone With The Wind” character. I saw his billowy scarf and mentioned it. Searching further for a “rhett butler costume,” I hit the exact description: Rhett was a Victorian dandy, and for neckwear he favored ascots. “Ascot” was the exact noun. (In the end, I dropped the whole idea because (a) a Southern belle in her hoop skirt couldn’t fit into a car, (b) they were at a Christmas party, not a costume party, and (c) they were minor characters anyway.) As Twain said (quoting his friend Josh Billings), the precise word is always best.
Frankly, my dear, it’s an ascott
When writing procedures, technical writers think about breaking down steps into a consistent series of understandable actions. The definition of an “understandable” action has changed over the years. In 1940, when Bell Telephone rolled out rotary phones to replace stick phones, they produced instructional films on how to use them. My career spanned the change of user interfaces from command lines to graphical interfaces. The first Macintosh User’s Guide taught users how to point, click, drag, double-click, and so on, and at one point my employer’s manuals had a standard appendix describing the same thing. Today documentation dispenses with that because tech writers assume everyone knows how to use a mouse, but we’re going through a similar interface change to touchscreen interfaces.
Similarly, in describing fictional action, writers have to decide on the level of atomicity. The standard writing-class example is placing a phone call. If you make the fictional narrative mistake of describing every atomic step of the process, the narrative halts unless the call will trigger a bomb. We understand that fictional characters have bodily functions; unless you want to call attention to some interruption, there’s no need to mention them. For a phone call, “He called his wife and lied that he was working late” is sufficient (and notice how much work “lied” does here). Interestingly, many kids today don’t know how to use a rotary telephone, and why should they? Hey, I don’t grasp features on my smartphone. The bigger the steps, the faster the action: In Galactic Patrol (1937), the next sentence after the new space academy graduate was invited aboard his first command was, “Under the expert tutelage of the designers and builders of the Brittania, Vice Commander Kinnison drove her hither and thither through the tractless wastes of the galaxy.” E. E. “Doc” Smith had a lot to get to, and no time to edit out clichés.
The same thinking that leads to concision in technical writing leads to direct communication of experiences in fiction. In the first example below, the editing advice is to use active voice; in the second, the advice is to remove filtering words:
Ensure that the wing nuts are finger-tight before proceeding. Tighten the wing nuts by hand.
He looked up and noticed that the sky was blue. The sky was blue.
Visual media such as film illuminates a whole scene, like the sun illuminates a landscape, allowing the viewer to choose what to focus on. Literature shines a flashlight with a narrow beam: the reader can focus only on what is illuminated by the stream of words you provide. Omit needless words and unnecessary details.
What’s different?
I won’t say I miss deadlines, but “the release is scheduled for Christmas, and your paycheck depends on meeting the date” is compelling; “do I write today or scroll through social media?” is less so. For me, less discipline has meant less focus. Setting time goals (finish a draft by the end of the year) seems to help.
High-quality technical writing is consistent. It’s common to use a controlled vocabulary. Similar items and actions must be described with similar, perhaps identical, language, particularly verbs: computer users click the button, never hit, punch, press, or anything else. (Smartphone users touch it.) However, consistency makes for hack fiction; original expression is rewarded. I’m still searching for the right words, but I no longer worry about writing to an eighth-grade level or restricting myself to a standardized vocabulary. For the sake of variety, if I want a long sentence I write one, and if color is warranted, I color. I seem to write particularly long sentences when listing things; for example, this passage is currently 100 words, 81 of them in the first sentence alone:
She was not going to chance some tiny unknown island pharmacy, so she assembled everything she could imagine needing: [long list of items]. The completed list was her longest ever. It resembled one of her ex’s pharmacy sales orders. Am I compulsive?
Wordle players are familiar with rearranging letters to form words: STALE SLATE STEAL LEAST TALES and so on. English sentences can be constructed in many different ways by rearranging words and clauses. Technical writers are trained to write active-voice, right-branching sentences, but I always used to roll sentences around in my head seeking maximum effect, from left-branching to right-branching, from passive to active voice, and to put the sting of the sentence in the tail, an idea from outside technical writing. Fiction writing is less structured, and now I’m free to structure a sentence any way I see fit. For example, I wrote this sentence: “He walked around the building and saw chaos everywhere.” The sentence is accurate but boring. I wanted to emphasize the chaos—the sting. I rolled the sentence all around, trying different words in different places:
He went all through the building. Everywhere was chaos. He went all through the building. Everywhere was tumult. He went all through the building. Everywhere was pandemonium. He went all through the building, and everywhere he looked, there was chaos. He went all through the building. There was chaos everywhere. He went all through the building and saw tumult everywhere.
Your opinions may differ, but I finally went with the boldfaced sentence as the first among equals.
The course “Building Great Sentences” covers cumulative and balanced sentences. A cumulative sentence is built up of clauses or phrases such as “This is the dog that worried the cat that chased the rat that ate the cheese that lay in the house that Jack built.” If you maintain the structure, a cumulative sentence can extend to any length. To show the morning of a stressed-out character behaving abnormally, I wrote:
She left her condo, got into her car, put on her sunglasses, lit a cigarette, cracked the window open, and hit the road.
Basically, a cumulative sentence is what in technical writing would be presented as an ordered or unordered list.
A balanced sentence is constructed in parallel; for example, “Ask not what your country can do for you—ask what you can do for your country” (John F. Kennedy), or “Not that I loved Caesar less, but that I loved Rome more” (Shakespeare). Too many balanced sentences can become singsong, but it’s nice when you can include them.
Technical writers are trained to write colorless, or at best friendly, prose. I never wrote as myself, but as my employer, and ideally, every writer on the team sounded the same. (I acknowledge the authors of the original Unix documentation, who injected subtle humor sometimes imitated, poorly, by engineers when they get punchy.) Fiction writing allows for a chorus of voices: characters, potentially all sounding distinctly different; a narrator; and an authorial voice describing or characterizing action, perhaps even interrupting to directly address the reader. Jay McInerney’s Story of My Life (1988) begins with a vivid first-person narrator’s voice:
I’m like, I don’t believe this shit.
(Trust me, the entire book sounds like that.)
For me, perhaps the greatest difference from technical writing is the unreliable narrator. (No jokes, please!) Vladimir Nabokov’s Lolita (1950) is the fictional confessional of a self-admitted pedophile whose account of his compulsive, doomed love for his stepdaughter, who we would today call a tween, is psychologically twisted, morally repugnant, and thoroughly unreliable. One brilliantly telling detail is that the narrator describes tweens that ring his chimes in loving, lavish, and minute detail, while describing those who don’t arouse him, and old women (over 16!), minimally and disparagingly. Lolita brilliantly limns the mind of its main character but, decades of censorship notwithstanding, does not reveal the voice or mind of its author.
A note on Grammarly
I’ve never been a good typist, and the more heavily I edit my work, the more obvious errors I make. To keep from embarrassing myself I purchased Grammarly Premium. The current Grammarly offers multiple levels of correction and advice. It red-flags grammatical errors, misspelled words, and doubled and missing words, and I’m happy to make those corrections. (I fight with it over my comma usage, which I can improve, but I’m writing fiction and contend that most people don’t speak in Oxford commas.) It also seductively blue-flags passages it thinks can be improved, and here I think about its advice.
The red underline flags a typo (which I fixed) and the blue underline flags a suggested rewrite (which I didn’t)
Finally, like every current product determined to jam AI down our throats, Grammarly offers AI-based rewrites of sentences and whole paragraphs. Its suggestions tend to make passages static and boring. If I sank to the level of accepting AI rewrites I feel I would no longer be the author of my work.
What do you think?
These are my observations on how fiction writing is, and is not, like technical writing. I may update this post as I learn more. Your comments are welcome!
Yesterday, 29 January 2025, the STC Board and Executive Director sent notice to members, stakeholders, and friends that “effective immediately, STC will permanently close its doors and cease all activities.” The title of the message was “The Future of STC,” but the message was that the future is null.
Today, many colleagues are posting messages and blog posts reacting to STC’s abrupt end. Their reactions mostly take the form, “As an [n]-year member of STC and [activity] volunteer, I am [reaction] to see it go.” Here’s my reaction, but I thought I would parse it to offer some useful information and context.
This announcement is predictable but sad. As a 42-year member who joined the Society in 1982 (and had just renewed), Fellow, chair of the first Certification Commission, President’s Award winner, and two-time president of the Boston Chapter—a founding chapter of the Society—I am bummed.
This announcement is predictable but sad.
Who could have seen this coming? Um…
Here is the year-over-year membership data over the last 30 years. As far as I know, the absolute peak membership of the Society was just over 21,000 in the spring of 2002, but declined steadily every year after that. I suspect 2025 would have seen membership drop under 1,000.
Note: This data is discontinuous. Before 2007, it was the membership at the end of the STC fiscal year on 30 June. From 2007 on, as the decline reached 50%, STC, perhaps understandably, stopped disclosing its membership to members. From then on, I used the membership data announced yearly by the STC election teller on 28 February. I believe the apparent membership drop you see for 2007 is an artifact of that change, but the data on either side is comparable.
As for my personal reaction, I have been a second-generation technical writer. STC was my professional home across a career spanning ten companies. STC members mentored me. I got jobs directly through STC networking. I invested considerable effort giving back to the Society over the years: judging scores of entries in the Boston, Alliance, and International Technical Publications competitions; writing many papers and presenting many times at the chapter, regional, and Society levels; serving at the chapter and Society levels; and mentoring dozens of rising practitioners. (I still have one I intend to keep working with.) I made lifelong friends. Of course I’m sad.
As a 42-year member who joined the Society in 1982 (and had just renewed),
I contacted the information address on another matter and received an automatic reply that addresses members’ likely top question: “Some of you are requesting dues refunds. The trustee appointed by the bankruptcy court will be reaching out to all dues paying members over the next few weeks with information and options.“
Board member (2007–2010),
I’ve already seen someone dance on the Society’s grave by blaming its demise on “years of mismanagement and bad decisions.” Well, I served on the Board, and to take the Board line, I supported its decisions, so I will stand up and accept my share of blame. But look at the data. Who would you blame for a 25-year membership decline? I assure you that this issue was at the top of the minds of every STC president, board member, and executive director the whole time. If the number of members hasn’t been the top KPI at the Society level it should have been. It’s been mine for 20 years.
I can also say that when I served on the Board, we blamed the decline after 2001 on the aftereffects of the events of 9/11, and that membership would recover. We were wrong about that. But if you look at the membership of other professional associations, this trajectory is not unique. The underlying issue is bigger than just STC. The final Board didn’t screw up; my Board didn’t screw up; the 2001–2002 Board didn’t screw up. Maybe we can blame Osama bin Laden, but I don’t think we can pin it even on him. I blame demographics, but what do I know?
Fellow,
A professional society fellowship is a lifetime honor, so when I received it in 2018 I told myself that even if I stopped paying dues I would remain a fellow for life. I didn’t anticipate outliving the Society, but I’m keeping my plaque.
chair of the first Certification Commission, President’s Award winner,
One of the first certificants told me at an STC Summit that he’d received a transformative raise from his employer for getting certified. When I came home and told my wife, I burst into tears. Why? Along with a volunteer task force, committee, and commission, I worked full-time for five years years getting the certification program approved and operational, but it changed peoples’ lives for the better. Receiving the President’s Award, in recognition of those efforts and on behalf of many others who contributed, was a signal honor and genuinely one of the happiest moments of my life.
I’m gratified that the STC Certification program today has over 760 certificants. I hope that the program continues, because it’s an ongoing benefit to certificants, employers, the profession, and the public.
and two-time president of the Boston Chapter—a founding chapter of the Society
STC was founded in 1952 by two organizations of technical writers and editors, one in Boston and one in New York. We in Boston were always conscious of our historical role and position in the Society. Our last few Chapter presidents and officers served multi-year terms and deserve thanks for their efforts.
To chapter leaders, who may have been feeling lost and bewildered by their membership decline: you are not alone and not to blame for what’s happened. Take it from someone who’s seen STC volunteers for over 40 years: you and other volunteers have worked just as hard as anyone ever has for the benefit of your members and the Society. It’s just a damned shame that you’ve been left literally holding the bag.
—I am bummed.
I am predictably and deeply bummed out. STC was a big part of my life. STC was very, very good to me, and I’m sorry to see it go.
Approaching San Francisco International Airport in a Boeing 737NG simulator
I wanted to be a pilot when I grew up until my eyes went bad. Fortunately, I got top grades on my writing homework, and eventually, I found adequate employment. But I’ve retained my interest in aircraft and flight all these years and passed along some of that interest to my oldest son. For his birthday this year, I booked him time on a Boeing 737 flight simulator and booked some for myself. We had a great time, and if you’re ever in Canton, Massachusetts, I highly recommend you experience it yourself.
The simulator reproduces the flight deck of a 737NG in exact working detail, good enough for pilot training. High-definition video synchronized to the controls is projected outside the windows, and sound effects, such as the engines revving up and down when you work the throttles, add to the realism. Even though the simulator doesn’t move, the overall effect is so convincing that when I climbed and banked away from the runway, I felt it.
A “co-pilot” who’s really a certified flight instructor sat in the second seat and patiently took me through the flight plan. He used a long pointer and a laser pointer to draw my attention to which display, knob, lever, or dial to look at or manipulate in an overwhelmingly complex layout.
There’s redundancy between pilot and co-pilot controls, but it’s still overwhelming [WallpaperSafari.com]
To give you some idea of the simulator’s flexibility, I chose to take off from Denver, climb west over the Rockies, and land in San Francisco. I managed to get the plane off the ground, avoid hitting mountains, and land in one piece. (I have the video to prove it.)
The 737NG is a highly computerized aircraft. Most of the flight is controlled by the autopilot, so “flying” consists almost entirely of setting and changing altitude, speed, and direction by turning knobs. That much I could do. Of course, the manual portions include takeoff, landing, and troubleshooting. The instructor programmed into my simulated flight a couple of anomalies to deal with: approaching traffic (another plane on a collision course, visible first on radar and then visually, that I had to maneuver around) and a smoke alarm in the forward lavatory (don’t even think about trying it). My son, who was more proficient, got hit with an engine failure and a stuck landing gear. Yikes! The flight crew draws a salary not just for knowing how to twist a knob but also for knowing how to deal with emergencies.
Earning My Pilot’s Certificate
Today, my corrected vision is better than 20/20. If I wanted to come out of retirement, totally change careers, and become an airline pilot, what would it take?
To become a certified pilot, you must demonstrate at least a minimum level of knowledge, skill, and ability (KSAs). To begin with, the knowledge required to operate, maintain, and repair a modern jet aircraft is immense. In addition to a minimum of 500 hours of classroom training, candidate pilots must pass a series of written tests, oral examinations, practical exams, and stage checks, including three formal exams given by the Federal Aviation Administration, followed by a practical test. Along the way you must earn six levels of certification from private pilot to airline transport pilot.
The fundamental skill of stick-and-rudder flying is unlike anything I’ve ever done. It absolutely can’t be taught by books, only by lengthy practice. Unlike driving, flying is three-dimensional. If you don’t want your passengers to feel like they’re riding on the back of a dolphin, you need to change both direction and altitude smoothly. Qualifying as a Boeing 737 pilot requires, at a minimum, 2000 hours of flight time on increasingly large aircraft. That’s a full-time year spent in the air. But before that, just trying to taxi from the simulator gate to the runway brought back my first driving lesson, which, as I recall, went badly. (Imagine you’re on a giant tricycle with the front wheel located behind and below you and controlled by a wheel by your left hand.) Our instructor told us consolingly that pilots book hours of time on the simulator just to practice taxiing.
Life-and-Death Interface Design Decisions
During World War I, men who sometimes had never even driven a car were taught the skills of flying: trusting their instruments when blinded by clouds or fog, marksmanship when aiming meant turning the whole plane, and keeping their engine running in different conditions and after gunfire damage. In World War II, people who might or might not have had flight experience were taught to fly multi-engine planes, a huge jump in complexity that brought its own problems. The four-engine Boeing B-17 bomber was complex but seemed like a pilot’s dream: every pertinent measurement was displayed in the cockpit, and every function was controlled by switches. But once deployed, planes were lost to inexplicable pilot errors such as raising the landing gear before landing instead of lowering the flaps. Was the pilot training inadequate?
Early designers (whom today we would call human-factors engineers) considered their users: young pilots, physically and mentally drained after flying ten-hour missions under fire much of the way, who were expected at the critical end to correctly choose between two identical switches placed next to each other. To distinguish them, designers changed the controls to levers with different labels, locations, colors, and shapes corresponding to their functions. After this design change, B-17s flew 1.8 million miles with no pilot confusing the two levers. To this day, Boeing designs those controls the same way: The flap control has a handle shaped like a wing, and the landing-gear lever has a literal wheel on it. To lower the flaps or the landing gear, you pull the levers down.
By the way, the engine instrumentation of a two-engine 737 is complicated, and for the B-17 was twice as complex. But from 1949 to 1959, the US Air Force deployed the B-36, a massive, transitional ten-engine bomber with six propellers and four jets (“six turning and four burning”). The flight engineer’s job on that aircraft was daunting. Even the dials had dials!
A B-36 flight engineer had to monitor and control all subsystems, including ten engines. Notice the built-in checklist. [TheAviationGeekClub.com]
Close Attention to Documentation is Required
Another innovation that came from the study of B-17 pilot errors was the checklist. No matter how well flight crews were trained, during critical moments of the flight there were simply too many things to do for them to remember. Checklists reminded them. In The Checklist Manifesto: How to Get Things Right, Atul Gawande writes about the pioneering development and use of checklists for the B-17. You can see checklists mounted on the yokes in the 737 cockpit photo above. Today, checklists help ensure the completion of complex operations in many fields, and they are familiar to all technical communicators.
Before my “flight,” I saw and purchased a 99-cent 737 checklist, which turned out to be the bare-bones list of takeoff, flight, landing preparation, and landing items that the instructor took me through verbally. (I was happy to pay a buck for a technical document.) There were still some 60 items total.
In addition to that checklist, I searched the web for 737 documentation and quickly found (but did not read) a flight crew operations guide (1,826 pages), a technical guide (374 pages), and a quick reference handbook (402 pages, which should tell you something), all highly controlled documents. I don’t think I found the full doc set. Of course, today’s pilots carry the necessary documentation on tablets.
The aircrat hardware is also documented. The history of every part of the airframe is recorded from manufacture to replacement, including maintenance logs. As a result, the documentation for the Boeing 747, printed out, is said to weigh more than the plane itself.
My Dream of Flying Comes Down to Earth
I may have the ability to fly an airliner level and land it without bouncing, but I’m years behind the curve in acquiring the requisite knowledge and skills to work as a pilot. For everyone’s sake, I’ll stick to passenger seats and simulators.
Here’s some authentic, historical pre-computer, pre-calculator thinking. In the 1970s, when four-function calculators first became widely available, users fell into two camps. Some, mistrustful of their skills, still calculated in their head but then checked their answer with a calculator. Others, mistrustful of the calculator or their ability to enter data correctly, used the calculator first but then checked its answer in their head. To this day I am in the second camp. This is partly a legacy of my academic course of studies: always check the units and the order of magnitude. (In cosmology, if your theory was right to within an order of magnitude, you were on the right track.)
This stubborness has a place in technical writing today. It’s not refusal to accept new technology or new facts, but rather refusal to accept things at face value. You may not be able to confirm that something is right, but you can check that it makes sense. I call this validation of plausibility. As President Reagan once said to Soviet arms-control negotiators: trust, but verify.
I draw a distinction here between copyediting, or applying company branding, copyright, logo, and style guide rules—all necessary checks expected even at a low skill level—and validating plausibility. It’s easy to point out a typo or an incorrect product name, and that level of vigilence is expected. But for a new practitioner, technical input from subject-matter experts is like the received word of God and not to be questioned. Well, here’s a secret: we are all human. Software engineers copy and paste code where they shouldn’t; accountants mess up the books; lawyers make typographical errors in laws; doctors write incorrect (or illegible) prescriptions. We know this applies to everyone in all fields. And yet it takes time and experience to reach the point of not accepting input you’re given at face value. Applying experience, logic, and common sense can help you recognize when some fact you’re given might not be—or even definitely is not—true.
There’s nothing wrong with a technical writer double-checking the plausibility of information. (Call it a “sanity check” if you will.) Most of the time, everything checks out, and no one needs to know you did it. When in doubt, ask. If you point out something that doesn’t add up, you just might find yourself a hero.
Don’t believe everything you read
Here’s an example. Let’s say you work fort a smartphone manufacturer and an engineer wants you to add this statement about a new product to the corporate website:
When meassured as a standard rectangular shape, the xPhome 15 screen is 6.35 mm diagonally.
I would expect even a new practitioner to fix the typo “meassured” without asking for permission or approval; that’s purely in the writing domain and no one will push back. Some would stop there, but an experienced practitioner should also notice the product name “xPhome,” double-check it against the product name list, and, if it’s wrong, question it. That’s a product-name issue with a defined right answer, and this is probably a typo for “xPhone.” Job well done, everyone! But… Is that screen size plausible? It’s a technical detail, so how dare I question it? Well, ask your digital assistant: Siri tells me that measures a quarter of an inch. The new phone model has a diagonal screen size of a quarter of an inch? No, that’s not plausible. Something—the number, the decimal point, or the unit of measurement—is implausible.
(Aside: I took a real website footnote and introduced those three errors; the actual text is clean, and the unit of measurement is inches. However, if I worked there and had had a second cup of coffee that morning, I might also have asked why the dimension was given only in inches, not inches and centimeters, as appropriate for a multinational corporation.)
Here are examples of things to look for:
Hardware: Do the weights of the servers in the rack add up correctly, and is the configuration overloaded? Is everything given in US voltages or European voltages, as appropriate? Is the top speed of the aircraft in the range of a jet fighter, a dump truck, or a flying saucer?
Software: Is a file listed but not described? Is every function name spelled correctly? Is the set of code or error messages parallel in structure (address space) and without duplicates? After you’ve documented 200 APIs grouped into sets of CREATE, DELETE, SET, and SHOW calls, is a new block with the calls ADD, KILL, CHANGE, and VIEW correct? (This last is for extra credit. When it happens, the developer is usually new and unaware of established convention, and the software architect will be very unhappy if that convention is disregarded.)
Medical: Do the percentages of study patients who experienced side effects match the actual numbers? (I wouldn’t touch the statistics but I can add.)
Financial: Spreadsheet formulas aren’t infallible. An accidental change to a cell can break the entire sheet. Spot-check the math and you can be a hero.
When you think you’ve spotted an implausibility, don’t be afraid to politely ask about it, but be humble. The first time you think something is wrong, you’ve only attained the “a little knowledge is a dangerous thing” level. Going in guns blazing and announcing that the chief architect made a mistake is poor tactics, potentially embarrassing, and possibly job limiting. Asking a polite question is a far better approach. For example: “Our documentation says the average transaction takes twenty milliseconds. You said here that you have reduced transaction times by twenty-five milliseconds. Isn’t that impossible?” Obviously it’s a mistake, but what? If you confront the person with an error, nothing good is likely to happen. Phrased as a humble question, it gives the chief architect a graceful, face-saving exit: “Of course, I meant 2.5 milliseconds;” “I should have said twenty-five nanoseconds;” “I was speaking of the slowest transactions, not every transaction.” Saving face is more important in some cultures than others, but it’s at least a consideration everywhere, so adjust your approach to the personalities involved.
Do your homework first
There’s a fine line between being curious and asking others to do your work for you. “Are you sure these numbers are right? You should double-check them” is making work for someone else. If you don’t think they’re right, you check them. Don’t assume something you don’t understand is wrong—you may simply not understand it. Do your research first! Then you can ask questions.
Verifying information to the extent that you can, and questioning implausible input, is a technical communication best practice. Over time, as you develop domain knowledge at your job, you will understand more, ask better questions, and spot implausible input more easily. But this practice itself is portable, and you can apply it to any field.
The effect of catching technical errors is to give your team the impression that you are competent, thoughtful, and thorough—all facets of a great professional reputation!
We loved the TV ad where a girl gives virtual-reality headsets to her grandfather, a Vietnam-era fighter pilot, and his buddies so they can once again experience the joy of flight. (The pilots are real, not actors, and the short film encompassing the ad that Xfinity released for Military Appreciation Month is a must-see tearjerker.) Just how realistic is the VR experience, anyway? If you ask me, it’s pretty good.
Inside my son’s VR headset is a whole new world
My youngest son splurged on a Meta Quest 2 virtual reality headset, and the other day he brought it, along with his tower PC, over to show it to us. To showcase the experience, he brought Riven, the great Cyan game originally released in 1997, now replatformed for Meta Quest. My son and I played Riven together when he was young—well, mainly I worked through the answer book while he sat in my lap and watched—so he thought it would be familiar to me. He walked through the familiar game landscape while I watched what he “saw” on our TV, and then he put the headset on me so I could explore while he monitored my progress and coached me.
Back to the island
An image from Riven (Cyan)
Without getting into the details of Riven, you are transported to a small island and must solve physical puzzles to escape it. The game is untimed, so you can fully explore the island and its mysterious structures at your leisure. The VR headset provides an immersive, high-definition, 360-degree view and positional audio; Riven implemented full three-dimensional views everywhere, from straight up to straight down and all the way around. When you move your head or take a step, your perspective changes, so you can literally look at and walk through the entire virtual space. (Tip: don’t turn around rubbernecking so much that you wrap yourself up in the cord.) The system maps out your physical locale—in this case, our living room—and your position within it, and alerts you visually, rather in the manner of a Star Trek holodeck, before you walk into your couch.
To let you manipulate objects in VR space, the headset comes with hand controllers, analogous to computer mice, that serve as your VR hands. You can reach out and touch objects in virtual space, and also click buttons to move forward virtually without taking a step, the way Riven used to let you click on an image to move toward it.
Riven provides detailed rendering, as impressive as when Cyan first introduced it, but now in 3D and moving. I found myself marveling at tufts of grass blowing in the sea breeze and gawking at birds overhead that had nothing to do with the game. Once I started exploring the island itself, the VR effect was so realistic that it triggered physiological reactions. If I moved my head abruptly or clicked forward too rapidly it made me slightly queasy. When I physically walked to the edge of a cliff to look down at a game element my body involuntarily flinched, and my son had to reassure me that the game wouldn’t let me fall off. (Had I tripped over the cable at that moment I don’t know how I would have reacted—probably spasmodically!)
In my experience, whenever I’ve been exposed to a new level of display detail, I’ve thought it looked “real,” until I saw the next breakthrough. Despite its remarkable verisimilitude, there are limitations to the VR system. I won’t say the Riven island looked real, and when the next next generation of graphics rendering hardware comes out the effect will probably look quaint, but to my eyes it quickly became acceptably realistic. Rendered on my son’s computer, I could move more quickly through the virtual environment than the system could paint the image, so some sights (such as a footbridge I was crossing) appeared ahead of me only after a lag.
A VR headset packs a lot of hardware, so while “touring” the island I never lost the sense that I was wearing one, the way I often forget I”m wearing glasses. The headset is bulky, not light, and the aforementioned cable can get in the way if you physically move around. It’s easy to get the hang of the controllers, but I believe another company makes glove controllers, which would track both hand and and finger movement. That sounds better.
What else have you got?
VR is a leap forward in realistic gaming. I expect a first-person shooter game where you could see a sniper on the roof and hear a gun being cocked on your left would be entirely convincing. A VR racing game, even played from the comfort of your chair, must be thrilling. But gaming not my pastime, so I won’t endorse any of the dozens of VR games currently available. (Current roundups are available here and here.) I’m also not endorsing the Meta product; VR systems are available from Apple, PlayStation, and others.
VR experiences other than gaming are available. Even something familiar like Google street map view would be transformed as a VR experience. But let’s think bigger. A VR experience good enough to fool your body enables physical exercise in virtual space. VR is unconfined by space, time, or reality, so the possible venues are unlimited as well. If tourist attractions bore you, how about the depths of the ocean or the reaches of outer space? NASA has more than enough photographic data to create VR tours of the International Space Station, the lunar surface, and Martian landscapes. If the present doesn’t appeal to you, how about the Jurassic Era? And anyone willing to invest the effort can create an entire fantasy world, like Riven, or a universe, like No Man’s Sky.
Virtual travel for the no-go years
My wife and I have reached the “go-go” stage in our lives, where we’re willing and able to explore new places. We know people who are in their “slow-go” years, willing to travel but limited by financial or medical constraints. Even where we can go, we risk becoming part of a noisome and increasingly unwelcome throng. We’ve been to the Great Wall of China as part of a crowded that looked and sounded like we were filing out of a stadium. Ecologically fragile Venice now restricts cruise ships and tourists. You need a timed ticket to visit the Louvre. Our own window of opportunity is closing.
How marvelous it would be to have VR recordings of tourist attractions—the Great Wall, the Pyramids, the palace at Versailles, Rome, London, Venice, the Smithsonian, the Louvre—that even someone in their “no-go” years, confined to a bed or wheelchair, could still visit and tour at leisure without fighting a crowd, a staircase, or a clock. It would be much more cost-effective and eco-friendly than a flight or a cruise. If more people were satisfied by touring virtually rather than physically, the crush in the real world would be reduced as well.
The bottom line is that my brief exposure to VR was intriguing, and I’ll be interested to see how the field develops. As a hard-core Apple guy, I know Apple Vision Pro is a top-of-the-line system for only ten times the price. Hmm., it’s nearly my birthday…
The tech world is agog with the capabilities and potential of artificial intelligence. AI is the hottest trend in decades, and pundits are all over the map predicting the scope of its impact. Every white-collar job, from the call center to the CEO’s office, can possibly be augmented, replicated, or outright replaced by AIs. Depending on who you listen to, the impact of AI could be nothing much, a huge impact on productivity without net job loss, the wholesale displacement of tens of millions of workers, or our destruction as a species. I confidently predict the correct answer is in that range.
In this post, I’ll touch briefly on what AI might be able to do in the realm of language, its current weaknesses in that realm, and the natural advantages technical communicators enjoy over today’s AI systems. (The rest of you are on your own.)
The Promise of AI
AI’s first real introduction to popular culture may have been when IBM’s purpose-built, supercomputer-based Watson defeated the two best human “Jeopardy” champions in 2011. Since then, AI capabilities have expanded with stunning swiftness across a broad front of human endeavor. An AI passed the standard bar exam in 2023. In a recent study, an AI passed the Turing test, fooling humans into thinking it’s also a human. Some people have even claimed that AIs have achieved sentience. The output from AIs seems poised to become indistinguishable from that of humans, to the consternation of essay graders and job seekers everywhere. Today, AIs are on probationary periods as Google and Microsoft search assistants, corporate chatbots, and graphic artists.
AI technology is rapidly advancing. Its greatest promise may be that with the effort and resources being poured into it right now, AI’s future may far outstrip its present, and quickly. But let me tell you, for right now, it had better.
The Pitfalls of AI
Watson parsed natural-language inputs and rapidly searched an offline database to produce correct responses faster than humans. As impressive as today’s AIs appear, they are, in a way, a significant step back from the Watson benchmark. The current generation of AIs is fast but suffers from a fundamental problem: you cannot trust AI answers, no matter how eloquent or convincing they sound. The industry term “hallucination” is a diplomatic way of saying that some AI answers are untethered from reality. Today’s AIs mimic human speech, but they are unable to reason, do any kind of math, or apply elementary logic. Consequently, they are wont to produce answers that are hilarious, horrifying, and sometimes dangerously wrong. Right now, AIs make unsuitable law clerks, software engineers, customer-facing chatbots, and research assistants. To me, today’s AIs are, in the philosophic sense of the word, nothing but bullshit generators.
Given how AIs need to absorb large language models to better predict the next word in a sequence—providing, in other words, highly developed autocompletion—they are a great demonstration of the old expression “garbage in, garbage out.” Today, AI vendors are sucking in everything they can obtain on the internet, even Reddit subgroups, hardly the acme of human thought. Worse, information sources aren’t weighted. AIs literally believe that everything they “read” on the internet is true. A Reddit joke post was apparently regurgitated, undigested, in a top answer on how to keep the cheese from sliding off pizza: mix in glue(!).
In an episode of the original Star Trek, Captain Kirk is about to be duplicated and floods his mind with angry, racist thoughts. The clone curtly dismisses a suggestion from Spock with the jarring, “I’m sick of your half-breed interference.” In response to threats of copyright infringement justified as “fair use,” some image providers are adopting a similar tactic, “poisoning” input data with false metatags, hoping that if their work is stolen for an LLM and used to train an AI, the results the AI produces will be wrong. Other actors are simply malevolent, manipulating training data with malware and phishing attacks.
Finally, current AIs are prone to the worst sin an information provider can commit: making stuff up. Writing for BuiltIn.com, Ellen Glover reported, “ChatGPT can generate URLs, code libraries and even people that do not exist, and it can reference made-up news articles, books and research papers).” It’s all fun and games until someone relies on an incorrect AI statement and dies.
My advice for now is to give AI less credibility than President Reagan once gave the Soviet Union’s word. Don’t trust, and verify. I suggest keeping an eye on Google’s AI Overview: many of the bad examples I cited originate there, and Google is actively trying to clean them up. If any corporation can fix a problem with its core product, Google can. Let’s see how they do.
The Value of Credibility
So, what’s a technical writer to do? Upper management is playing with a new toy that’s faster and cheaper* than we are. If an AI can crank out hundreds of pages of technical material in minutes, we’re going to be out of a job soon, right? Well, hang on. I think there are several big reasons why the profession isn’t doomed just yet.
For one thing, working for a client involves access to the client’s products and subject-matter experts. Your work is inherently more credible than the work of someone or something unaffiliated with the product.
A technical open-source LLM will consist of existing technical documents posted to the web. The technical documents generated from this model will sound like the large corpus of public-facing libraries created by IBM, Oracle, Amazon Web Services, Microsoft, and other major vendors. This isn’t in itself an issue. But if your company tries to generate technical documentation that way, AI will provide sound-alike technical information, which will be incorrect. Of course, your company can and should limit its input to its own proprietary specifications and internal library—you know, from the Confluence pages and SharePoint site that no one has cleaned up in ten years. How will the AI distinguish between correct and incorrect specs, or between current, proposed, and abandoned features? And how will your legal department feel about loading your proprietary information into an LLM that uses your input as training material?
Assuming your company opts for a slim language model consisting only of its own current, vetted functional specifications, an AI might be expected to re-present the information in an acceptable style. (A prompt might be: “Using Simplified English and an eighth-grade reading level, create procedures for system administrators to configure the router.”) But this lacks something technical writers do that I consider something of an unspoken black art. When we turn a specification into customer information, we don’t include everything in it. Information on how the engineer implemented a feature and how its algorithms work is not meant for customers. I can’t articulate how we decide what to filter out; it took me years to acquire the experience and confidence to do so. Without a librarian, a library is just every book that the community can afford to acquire. Librarians are curators. We curate technical information for our clients and customers.
I’ve always had the gift of gab, and I can write a persuasive sentence even if it’s incorrect. As time-consuming and ego-bruising as a technical review can be, it is a strength of our work process. A reviewed and approved document is far more likely to be correct. Fact-checking is required if incorrect information has legal consequences—and technical information always carries legal weight, regardless of where it comes from. Can you correct an AI’s output? So far, programming AIs, which produce straightforward compiles/doesn’t compile output, can’t incorporate feedback. Even if there’s a mechanism to review and correct AI output, implementing my advice to verify everything will significantly reduce AI’s seeming time and cost advantages.
Finally, as professionals, we have ethical standards. One basic definition of quality technical writing is clarity, concision, and correctness. Call it pride in our work. Even absent review, our own sense of ethics drives us toward correctness. We don’t make stuff up.
The challenge of AI is to create correct, credible information. Today’s AIs produce information that sounds credible but is not correct. We’re all about correctness and credibility. I think we can meet this challenge.
*[Update 11 July 2024: I’ve learned that one of my assumptions is wrong. AI is not cheaper than we are. In fact, the CPU and power requirements are very substantial.]
Steven Jong 
