If there’s one skill that will get you moving in software, it’s coding. If there are two, the second is architecture, but if there are three, the third is certainly technical writing. We write every single day—emails to our managers, instant messages to ask questions of busy people, manuals for customers, comments in our codebases, design documents, etc., etc., etc., and my personal experience has been that crisp writing can save enormous confusion and make your ideas far more persuasive. It also has a less obvious benefit—good writing is unreasonably impressive to most engineers and managers and can build your reputation.
Be concise: Anything that doesn’t clarify obfuscates. Holding precision constant, take out absolutely everything that doesn’t improve the reader’s understanding. Can you remove a word? Can you remove a paragraph?
Emphasize conclusions: Readers usually care most about high-level conclusions; make those crystal clear, and don’t drown the reader in details. Lead with a tl;dr!
Put yourself in your readers’ place: Ask yourself what matters to them, what they know, and whether they will understand what you’ve written.
Guide readers with clear structure: Clear structure helps readers follow your writing. It’s often best to start with an introduction/summary, follow with clearly titled sections addressing specific areas, and close with a conclusion. Use bulleted lists liberally.
Use simple language: The simplest language that will convey your meaning is usually the best choice for readability. Any terminology that is not highly likely to be known to the reader should be replaced or defined; is the reader going to understand the technical term you’re about to use?
Provide ample context: When you introduce an idea or piece information, the reader should already have the context they need to reason about it, and you should explain its relevance immediately; otherwise, it will confuse them.
Lead with your most important points: Writing, from sentences to paragraphs to whole books, is usually clearest when it leads with its most important points.
Edit for precision: Precision may be the highest virtue in technical communication; reread your writing and ask, does it say exactly what I mean?
For engineers, the two most common problems are failing to provide enough context (assuming the reader knows everything you know) and giving too much detail (forgetting that the reader doesn’t care about everything you do), so if you do your very best to resist those temptations, you’re off to a good start.
A Note About Structure
A razor-sharp introduction that summarizes everything else. Our introduction makes sure that our readers want to read everything that follows and understand its purpose; it should ensure that if readers give up early, they’ll still walk away with the most important points.
Sections delineated by headers or paragraph breaks.
Section ordering that sorts first for comprehensibility—necessary context first—and then by importance—most important points in early, before the reader gives up.
Our introduction is our most important section. It catches the reader’s attention and creates momentum; it should give them something to remember if they quit before the end, which many people will.
Each clearly marked section after should be a landmark that reminds the reader where they are in the universe; you’ll find my best efforts at following this principle throughout this book, including in this chapter!
When you’re finally done writing all your sections, you’re not done—you’re ready to edit.
Editing
Editing is a painful process, a fine art, and the subject of many books better than this one. Its concept is simple: reread your work, find things to improve, and fix them. We can edit at both the micro level—improving each sentence one by one—and at the macro level—improving overall organization and content.
The microscale improvements are easier, so I suggest you start there and use that process to discover bigger problems. This process is a while loop: we start at the top of our document, read every sentence, improve each one, and repeat until we simply cannot improve any more.
- 1.
Can I take out words?
- 2.
Can I write a simpler sentence?
- 3.
Is there enough context?
Remove Words
This is the simplest, easiest, and by far the most effective editing technique of which I know; we go back through our text and reread every single sentence we’ve written, identify all the words we’ve added that aren’t strictly necessary, and take them out (or, in some cases, simplify). Here’s an example.
This is the simplest, easiest,1 and by far the2 most effective editing technique of which3 I know; we go back through our text and4 reread every single5 sentence we’ve written,6 identify all the words we’ve added that aren’t strictly necessary7 unnecessary words, and take out (or, in some cases, simplify)8 remove them.
- 1.
“Easiest”: “Simple” gets the idea across on its own, people will figure out that it’s easy.
- 2.
“Most effective”: Is plenty strong, “by far” is gratuitous.
- 3.
“Of which”: Adds no information.
- 4.
“Reread”: Already implies going back through the text.
- 5.
“Every single”: This phrase is stronger than “every,” but we don’t seem to need to be strong here.
- 6.
“We’ve written”: We already know that we wrote the text.
- 7.
“All the words we’ve added that aren’t strictly necessary”: We can be more direct and briefer at the same time with “unnecessary words.”
- 8.
“... take out (or, in some cases, simplify)”: We pay a small amount of information, but we buy back quite a lot of words.
We’ve reduced our word count from 52 to 21, saving our readers’ precious time and energy for more valuable purposes, like reasoning about our ideas. This technique is both easy and effective—the return on investment is extremely high, so make it your #1 editing technique. I wouldn’t send any written communication out the door without a word removal pass.
Simplify Sentences
<Subject> <Action> <Object>. <Subject> <Action> <Object>.
The infrastructure team is migrating the data to the cloud. This migration blocks big schema changes. They expect to finish by the end of the week, and we can launch this feature at that time.
We can launch this feature after the infrastructure team finishes the migration of the database to the cloud, which blocks big schema changes but should be finished by the end of the week.
Get the Context Right
Does the reader know everything they need to know to understand what I’ve said?
Will the reader believe me, or do I need to justify myself?
Am I explaining something the reader already understands?
For financial transaction data, we will need greater consistency than OurDistributedDataStore guarantees. Therefore, those records will be stored in OurReplicatedACIDDatabase, which should offer sufficient throughput for this workload. Our application will be written in Java, which supports Object Oriented Programming; inheritance will allow good code reuse.
The consistency and performance of distributed databases are notoriously subtle; almost any audience will need some clarification. Even if the reader knows exactly how OurDistributedDataStore works, they probably don’t know exactly what guarantees the financial transaction data needs; we should tell them. As for OurReplicatedACIDDatabase, the reader probably understands that it’s super-consistent, but will they trust that the throughput is high enough without any evidence? Finally, we have an error in the opposite direction—our audience is programmers, and telling them how Java OOP works is condescending (that’s a real example that I saw happen last week!).
For financial transaction data, we will need greater consistency than OurDistributedDataStore guarantees; account balances for each user must be stored in separate rows, and transfers between them must be atomic. OurDistributedDataStore can only guarantee consistency for transactions on a single row. Therefore, those records will be stored in OurReplicatedACIDDatabase. While it does not offer the same throughput, we have load tested it up to 15,000 transactions per second, 10x the maximum projected QPS in 1 region.
Even careful writers will sometimes explain too much or not enough; when you’re deep in a subject, it’s hard to tell the difference. Once you’ve edited your little heart out, you can stop modeling other people’s minds and ask a real live colleague for feedback.
Spelling, Grammar, Capitalization, and Punctuation
I’ve known many effective and admired engineers and managers who write with poor spelling, grammar, and punctuation; it isn’t any kind of deal-breaker. Still, I advise you to get things right if you can; not just because I’m old-fashioned but because I think errors are just a little bit distracting and their absence makes a more professional impression.
Spelling is easy in this day and age—trust your spellchecker and double-check meanings in a dictionary if you’re not 100% sure of a word. Pay attention when your Word processor shows you red.
Punctuation and capitalization aren’t too bad either—start sentences with capitals, end them with periods, and you’re doing pretty well. Commas, colons, and semicolons are error-prone little tricksters, but Google Docs can often flag a mistake.
Redis is quite efficient for small payload sizes, but it can degrade significantly for larger objects | We need a comma because both halves have a subject (“Redis”, “it”) and a verb (“is”, “can”) |
Cassandra is optimized for high write volume but can struggle with heavy read traffic | We don’t need a comma, because the second half (“can struggle with heavy read traffic”) doesn’t have a subject |