Has plain language deepened or ruined our delight in language?
- Simple versus complex language
- Comprise
- Language as a tool of expression
- Rhetorical play in programming language
- Questions and dilemmas
Listen here:
Simple versus complex language
My wife is in a master of liberal arts program at Stanford. When she writes an essay, she asks me to read it and provide feedback. Every time I review an academic essay, it reminds me of the stark differences in language. In tech comm, most of the more interesting, flavorful words she uses in her essay are off-limits for technical documentation.
For example, here’s a smattering of words and phrases she used in her last essay:
- imposed didacticism
- pearlescent hues
- erstwhile acolyte
- progeny
- wanton
- placatory efforts
- intangible
- ephemeral
- uncannily
- evocative
- existentialist ideal of transcendence
- immanence
- blessed cessation of incessant demand
- litany
- emotional expenditures
- begrudge
- solicitous weather forecasts
- ebbed in bolstering
- travesty of symbiosis
- unfathomable pit of neediness
- modulating
- deputizing
- chivvy
- yonic
- staunching
- counter-narrative
- foisting
- catechism
- talisman
- culminatory
- inaugurated
- commodity
- promotional conventionality
None of those words would be welcome in technical documentation. Instead, best practices for language in technical documentation are to use simple, unambiguous words that have one easy-to-understand meaning. You also use short sentences, small paragraphs, and frequent subheadings.
Despite the technical writer’s attempt at simplicity, technical documentation struggles with its own jargon. In a topic I was working on last week, the following words might be just as challenging as the previous academic ones:
- Android Nougat
- Fire TV Generation 2
- Android 7.1.2, level 25
- Fire TV Edition
- backported Marshmallow
- Lollipop, or Android 5.1, level 21
- uplevel
- permissions at runtime
- linking to private libraries
- normal and dangerous permissions
- declared in your app’s manifest
- revoke individual permissions
- single binary targeting multiple devices
- gyroscope permissions
- public NDK APIs
- Private API
- Picture in Picture (PiP)
- Content Recording
- Time-shifting APIs
- Apps & Games Services SDKs
- in-app purchasing
- parity with Nougat
- API level
- memory on load
- target devices
Build.ModelBuild.VERSION.SDK_INT- dependencies
- SDK add-on
Imagine if you were to use academic language and technical jargon? That would be a one-two punch for incomprehensibility (though it would score a ten for comedic effect).
The difference in style between academic essays and technical documentation isn’t anything new. But I’m a bit troubled by it. After working many years in tech comm, much of my wife’s vocabulary is no longer part of my lexicon. I’m constantly going to the dictionary to look up words when reviewing her essays. It makes me feel out of step with my English BA and MFA background.
More importantly, in giving up these words, I have a sense of having lost something — my delight in language, in learning new words, and in reading and enjoying the eloquence of an author. Now when I read an author who uses more sophisticated language, I find myself asking, couldn’t the writer have expressed this in a simpler way? Why use that word instead of a more familiar one? My distraction with the language often poisons my attitude toward the content and author.
This is especially the case when reading academic essays. I have to constantly remind myself that my wife is writing in a specific discourse community that expects complex, hard-to-read language.
Comprise
As an example of plain language versus complex language, let’s look at a specific word: comprise. From a plain language advocate’s point of view, is there ever a time you should use comprise? Probably not.
In Wikipedia’s article on New England, the entry begins:
New England is a geographical region comprising six states of the northeastern United States: Maine, Vermont, New Hampshire, Massachusetts, Rhode Island, and Connecticut.
In technical documentation, a guide might use similar language:
The system comprises submodules A, B, and C.
But the question is … why use comprise here? Wouldn’t “consists of,” “includes,” or “is made up of” work equally well and be a lot more understandable?
The system consists of submodules A, B, and C.
or
The system contains submodules A, B, and C.
or
The system is made up of three submodules: A, B, and C.
The substitutes all work well. Additionally, comprise is even more problematic because of its slippery allowances around correct/incorrect usage. Apparently, there’s almost no wrong way to use this word. If you look at usage discussions for comprise in dictionaries, you’ll find that these constructions are also allowed by usage panels:
- New England is comprised of six states.
- Six states comprise New England.
See Webster and other sources for details.
In fact, comprise originates from the French word for “comprehend.” This seems a little odd until you think of phrases like “a comprehensive exam,” which is an exam that includes or comprehends every part of something. In that sense, you could also say that “New England comprehends six states,” though this use of comprehend is less common. (Still, in an academic essay, you might purposely use this word, especially if you’re describing something French.)
Comprise actually tells you more about the people using it than anything else. Many people who use comprise are trying to hypercorrect their grammar to sound impressive (so be flattered that they’re dressing up their language for you). If someone says “is comprised of,” it usually means the person is unfamiliar with the traditional usage of the word (in more judgmental terms, a bit unlettered). But when someone objects to the phrase “is comprised of,” correcting the speaker, it shows they don’t understand that this alternative usage is also acceptable, even if is rejected by many grammarians. This is why my ears always perk up when I hear the word “comprise.”
At any rate, tech comm’s focus on precision and clarity means the word “comprise” is pretty much off-limits. This word joins thousands of other words that have become extinct. Like the saber-tooth tiger and the wooly mammoth, “comprise” will eventually join apanthropinization, nerterology, and scandiscope.
Language as a tool of expression
For the literary essayist or novelist, language is a tool for expression. The more words you know, the more precise you can be in finding the exact word or phrase to describe something. When my wife writes her essays, maybe there’s no better phrase to capture her meaning than “erstwhile acolyte.” But in my head, I ask, would “former follower” or “previous disciple” not have worked equally well? Is it always necessary to send readers to the dictionary? Then again, perhaps there’s a play on words she’s going for (partial alliteration), or maybe she’s mimicking the diction of the early 20th-century author (her essay focuses on Virginia Wolf), or she might be mocking someone by using a pseudo-formal phrase.
I’m 42 years old, and I don’t think I’ve ever used the word “erstwhile” in either speech or writing, let alone “erstwhile acolyte.” Why would someone decide to suddenly use this phrase instead of something simpler?
The Simplified Technical English (STE) dictionary limits the number of words you can use to around 900. Any word that has multiple meanings is usually restricted, or if used, can only be used in its most conventional way. Would literature be better off following the guidelines of Simplified Technical English? Is it time to move “erstwhile” to the growing list of extinct words?
No, of course we can’t force literature to follow simplified English without gutting the English language. Eliminating huge chunks of the language, however complex or arcane or hard-to-understand, would be a mistake. Although STE has a place in technical documentation, which is already overflowing with its own impenetrable jargon, applying the same plain language principles to other genres would be the equivalent of removing all non-rainbow colors from a box of crayons. (No teal, no periwinkle, no burnt sienna. Just blue, green, yellow, etc.). What a boring world that would be.
Ultimately, our thoughts are made up of words. The more words we have, the more tools we have for both constructing and expressing our thoughts. Many words often express little ideas in themselves, sometimes revealing a whole philosophy in a single word.
Using phrases like “blessed cessation of incessant demand,” as my wife writes, is not always antithetical to communication. It’s surely possible to be both sophisticated, playful, and clear. And yet, my delight in this language has been irreparably damaged.
Rhetorical play in programming language
Although documentation usually doesn’t have sophisticated or playful language, there is sometimes a playful tone in docs. Android candy release names (such as Kit Kat, Lollipop, Marshmallow, Nougat, Oreo, etc.) inject a little fun into programming. But sometimes programming docs also sneak in little irreverent remarks, or slide into a playful and quirky tones, often in snarky code comments, as bleary-eyed programmers struggle against a baffling or insanely intricate piece of code. You also see these tones commonly in third-party guide books where authors have latitude to cut loose and be more authentic.
I once read a programming book on Java where the author explained the reason for this playful, irreverent tone. The author explains that programming tends to be dry and boring (programming is, after all, describing interactions with a non-human device). As such, by adding a little quirky, irreverent tangent every now and then, you wake up the reader and remind each other that you’re both human. Tim Wright explains:
Coding can always be a little more stressful than we would like, so don’t be afraid to inject some humor into your comments. As far as brightening up someone’s day when they’re eyeballs deep in code, it doesn’t get much better than reading a funny comment someone left. I’ve even caught myself laughing at comments I’ve written in the past. It’s always a nice surprise and lightens the mood. (Chapter 9: Code Design) See Learning JavaScript: A Hands-on Guide to the Fundamentals of Modern JavaScript
This non-standard tone is rarely allowed in company style guides, since companies often have many technical writers and so need to adopt a consistent and general voice (which they usually describe as friendly and helpful, but which is usually just professional and boring).
Unless you’re writing tech docs in a third-party guidebook, you’re probably stuck with a standard, professional tone coupled with a form of Simplified Technical English. You can’t break the professional tone nor delight in any kind of word play. In fact, eloquence and diction are usually far from my mind when I’m working on tech docs, as I’m just trying to understand what I’m even writing. As I said earlier, tech comm (particularly developer documentation) has enough issues in simplifying its own technical jargon, so making everything else as simple as possible is a must.
Questions and dilemmas
Where is the issue, then? Many of us studied literature for years in college, or we wrote (or aspire to) write creatively. The idea of combining language with technology for a career in technical writing appealed to our literary side. We had the idea that we could use our command of the English language to shape sentences, articulate complex ideas, and play with words all day like a child playing in a fountain at the park. Has operating in simplified vocabulary for years on end made us essentially sub-lingual and hostile to literary or academic discourses? On a deeper level, does our limited language (900 allowed vocabulary words) trap us in simple thoughts?
Or instead, perhaps I’ve been looking at this all wrong. Perhaps we technical writers have been cured of a linguistic illness that infects so many others with poor communication. While academics write in 20-line sentences and employ polysyllabic words that 90% of the population has never used, maybe technical writers have become the St. Francis of language. We have thrown our ornate phrases down to the streets, sold our excess adjectives, given our pluperfect verb tenses to the poor, and simplified our linguistic lives with singleness of purpose so that we can be free.
By stripping away fuzzy, ornate speech, we focus on precision in meaning. We convey ideas to readers in shorter, more compressed speech, increasing the efficiency of the exchange between the writer and reader.
Maybe. I’m not really sure whether technical writers have won or lost when it comes to language. We have traded eloquence for simplicity. Becoming a technical writer has poisoned my attitude toward academic language. I cannot read my wife’s essays without stopping to wonder, when I run across a phrase like “existentialist ideal of transcendence,” whether she could not have just said “find meaning and purpose” or “rise above the mundane to be free,” or even what that phrase could possibly mean, if anything. And even if it does convey meaning, what are the chances that the reader’s interpretation matches the author’s intent? Here I suppose I would like her to supplement her text with a brief concept diagram.
About Tom Johnson
I'm an API technical writer based in the Seattle area. On this blog, I write about topics related to technical writing and communication — such as software documentation, API documentation, AI, information architecture, content strategy, writing processes, plain language, tech comm careers, and more. Check out my API documentation course if you're looking for more info about documenting APIs. Or see my posts on AI and AI course section for more on the latest in AI and tech comm.
If you're a technical writer and want to keep on top of the latest trends in the tech comm, be sure to subscribe to email updates below. You can also learn more about me or contact me. Finally, note that the opinions I express on my blog are my own points of view, not that of my employer.