Update the docs. Send that email. Would you like to submit a post to the company blog? Oh, and a conference talk — you would love to give a conference talk, right?
You write constantly, and whether you view it as a chore or a joy depends on the depth of your writers toolbox.
After nearly five years as a producer at Treehouse, an online school teaching web development, I have observed several patterns among new technical writers. This article is meant to help you break out of those common patterns and write confidently.
This article is not a thorough grammar lesson. If you are unclear on the difference between dependent and independent clauses or need an overview of punctuation rules, skip to the Recommended Resources.
Writing succinctly is not an argument against long articles or comprehensive documentation — this article certainly isn’t brief. I advocate for efficiency. Whether trained by school assignments with word minimums or just uncritical, most of us write too much. Beyond approaching each draft with a ruthless cutting mentality, there are several ways to write short from draft one.
Be mindful of needless transitional phrases. If it goes without saying, why say it? Leading with phrases such as we’re going to or as you can see wastes real estate. Introductions are fertile territory when hunting for these redundancies.
Prepositions are words that connect or relate words and clauses to one another. They usually precede a noun or pronoun and connect it to another structure in the sentence. Notice words such as about, after, around, at, before, by, for, from, in, of, on, and to. These words, among others, begin a prepositional phrase.
When struggling to tame an unwieldy sentence, identify your prepositional phrases and ask if they are necessary. Is there another way to construct the sentence that is both short and clear?
On the screen, you can see a bunch of text from the author, and, for our purposes, the article seems wordy in multiple sections from the beginning to the end.
The article seems wordy.
This example is intentionally exaggerated, but I hope you see the problem. Mine your sentences for prepositional phrases and exorcise those that have not earned their place.
Are prepositional phrases always bad? No, the goal is to be intentional.
“To get started, install the package from npm or yarn.”
This sentence contains two prepositional phrases: “To get started” and “from npm or yarn.” Cut the first. However, “from npm or yarn” adds necessary context.
A solution to both the redundant and prepositional phrase problems is to use the imperative mood. This grammatical construction is often used but rarely discussed. Think of imperative mood as a command.
- Pass the salt
- Run the tests
- Push the commit to GitHub
The directness of imperative mood might seem rude, but it doesn’t have to. I use the imperative mood to axe most introductory phrases.
We are going to press the up arrow in the console to see the previous command.
Press the up arrow in the console to see the previous command.
This may not seem like a big win, but I saved four words in this single sentence without losing any meaning. As you review your writing, I am sure you’ll encounter many uses for the imperative mood.
Run-on sentences contain multiple independent clauses that are not separated by a colon, semicolon, or comma and coordinating conjunction.
The fix separates independent clauses using either a period or comma and coordinating conjunction. Though I’ve fixed the run-on, the construction is still wordy and confusing. I can do better.
Is the second part of the original run-on necessary? I cut it. I then rewrote the sentence in active voice — more on that later. The point is that run-on sentences create weak writing, and they must be corrected.
A comma splice occurs when two independent clauses are linked by a comma only. Independent clauses should be joined by a colon, semicolon, or comma and coordinating conjunction.
Python is a great programming language, it’s easy to read because the syntax is so simple, I really like the language.
Python is a great programming language. It’s easy to read because the syntax is so simple. I really like it a lot.
In case you don’t remember the coordinating conjunctions, memorize this acronym: FANBOYS (For, And, Nor, But, Or, Yet, So).
Be your own magazine editor and stick to a word limit. What if you had to fit all the information into 500 words? Working within a constraint reveals the best in us. You may be surprised by your efficiency once you abandon the freedom of an infinitely scrolling web page.
If your writing confuses people or your docs leave the audience wanting, you likely need to be more explicit and thorough.
Ambiguous pronouns are the first place to look when clarity is your issue. Look for words such as it, that, and this. When in doubt, explicitly refer to the subject.
The client sends a GET request to the server. It processes it with middleware and generates a response, which includes HTTP headers and a response body. Then, that is sent to the client.
What is it? What is that?
The client sends a GET request to the server. The server processes the request using middleware and generates a response object. The response object includes both the response body and any HTTP headers. The response is then sent to the client.
By being explicit, I eliminate potential confusion about the client, server, and response in this example. Explicitness is especially important for beginners, and, remember, everyone’s a beginner.
Clarity is another reason to cut words elsewhere. Clarity may require verbosity, so regard your words as a finite resource to be spent on what matters most: clarity.
When a sentence is written in active voice, the subject of the sentence performs the action specified by the verb. When a sentence is written in passive voice, the subject of the sentence is acted on, and the actor is either omitted or included at the end of the sentence, often in a prepositional phrase beginning with the word “by.”
- The request (subject being acted on) is processed (verb) by the server (actor).
- The article (subject being acted on) was written (verb) by Wade (actor).
- The Pull Request (subject being acted on) was merged (verb) (actor omitted).
- The server (subject performing action) processes (verb) the request.
- Wade (subject performing action) wrote (verb) the article.
- I (subject performing action) merged (verb) the Pull Request.
There are appropriate uses of passive voice, and some argue that active voice should apply only to animate actors and not inanimate objects. Use your judgement and be careful not to change meaning. However, I’m almost always in favor of rewriting in the active voice.
Disagreement can be especially confusing in technical writing. Disagreement refers to a mismatch between singular and plural nouns, pronouns, and verbs.
The company of 20 members are midway through their new product release.
The company of 20 members is midway through its new product release.
The subject is the singular “company.” The prepositional phrase, “of 20 members,” introduces the plural noun, “members,” and the incorrect verb and pronoun follow.
Disagreement is another reason to be mindful of prepositional phrases. Your subject is never in a prepositional phrase. Find the subject of your sentence and conjugate appropriately.
When you are tempted to use a meaningless adverb such as really or very, examine your verb choice. The same goes for exclamation points. Adding energy or emphasis requires better verbs, not modifiers and punctuation.
- Wade ate the pizza really really fast!
- The water completely ruined my phone!
- Wade devoured the pizza.
- The water destroyed my phone.
One side note here: active writing with strong verbs is not the same thing as littering the world with hyperbole. To my knowledge, no one has ever actually been eviscerated by a tweet, despite the clickbait headlines.
Technical materials should shun words such as simply, obviously, and clearly in reference to the subject. These words, among other dismissive terms, add no meaning to your writing. Unfortunately, they do communicate that the topic should be easy, simple, or obvious.
Examine your use of these empty adverbs. You will find that cutting them not only does no harm but improves your work.
Reading aloud catches most glaring errors. Reading aloud does not mean quietly murmuring to yourself. Find a private place, and read at full volume. Is that sentence too long? Well, you can’t read it without running out of breath, so … .
In addition to reading aloud, I recommend a second type of proofreading practiced by one of my journalism professors, the late Tom Wheeler. He would read once at regular pace to ensure everything flowed well and made sense. He would then read slowly — word-by-word. This second proofread catches small typos and easily missed grammatical errors.
I learned one of my favorite pacing exercises from Mary-Kate Mackey, another one of my journalism professors. She had us count the number of words per sentence. This exercise quantifies the cadence of your writing. Are all your sentences between 17 and 20 words? Do you have any sentences longer than 30 words or shorter than 5 words? Consistently short, medium, or long sentences create monotony. Add variety so that a piece doesn’t become too choppy or too drawn-out.
These guidelines and rules are meant to be broken. My writing on the Treehouse blog follows the above conventions, but I also break from them. The Treehouse audience is used to video, so the articles are written in a conversational tone. Sentences begin with “now” and “so.” I attempt to talk to the reader.
You will learn to match a publication’s style and voice. However, the principles above still apply, and rules must be broken purposefully. Be honest. Are you writing in a style, or are you working from a limited toolbox. Break the rules, but build your skills first.
With that in mind, the recommendations that follow will help you along the way.
- Write Better Right Now: The Reluctant Writer’s Guide to Confident Communication and Self-Assured Style by Mary-Kate Mackey
If you found the above article helpful, Write Better Right Now is my first recommendation. Consider it a one-stop-shop for those with little formal training.
For those who need a better foundation in English grammar and style, the above resources are your friends. I am not a strong copy editor, and I regularly reference my style guides and dictionaries, so know that these books will serve you now and in the future. Think of them as your docs for writing.
Why the Chicago Manual of Style? It’s opinionated and thorough. I prefer an opinionated guide that provides rules for most situations. When in doubt, have rules and follow them.
- A Writer’s Coach: An Editor’s Guide to Words that Work by Jack Hart
- Bird by Bird: Some Instructions on Writing and Life by Anne Lamott
- The War of Art: Break Through the Blocks & Win Your Inner Creative Battles by Steven Pressfield
A Writer’s Coach was assigned to me by Mary-Kate Mackey during journalism school, and I still revisit sections. If you’re looking for expanded guidance on writing powerfully or when to break rules (or what’s really a rule), this book is wonderful.
Bird by Bird honestly communicates how it feels to be a writer, and I love Lamott’s emphasis on writing bad first drafts.
The War of Art speaks to the discipline required to write professionally. If you are struck with writer’s block or trapped in the I-will-start-tomorrow loop, this book is worth the read.