Improving as a Technical Writer

Wednesday, June 1, 2022

A brief definition of technical writing

Writing is an immense field. It includes poetry, short stories, journalism, haikus. Technical writing is about communicating information related to technical topics.

Improving at technical writing requires a focus on this particular type of communication. Technical writing favors efficiency and clarity.

Why is technical writing important to me?

I immigrated to the United States (from France) in 2012 and I’ve been trying to get to fluency in my communication ever since. Technical writing (for me) is about making technical ideas and concepts accessible to others. It gives me an opportunity to be heard, on a more even footing with others. I get to craft my message more carefully that way.

Why might technical writing be important to you?

The software industry has recently shifted to remote-first. It forces most communication to be in written form
Technical writing is the basis of asynchronous communication for engineers. Text is async by nature: it can be consumed whenever convenient for each reader
Text is universal. Can fit on all screens, terminals and programs.
Writing is a powerful thinking tool! Writing forces coherent thoughts and highlights gaps. If you think you understand something, try to write about it. Writing is a Litmus test to answer “do I understand this well enough?”. More on this topic at Writing is Thinking
Writing is a powerful teaching tool! It’s the most scalable and flexible way to teach dozens, hundreds or even thousands of people about something. That’s because text is a universal format. Diagrams or visuals are harder to produce and maintain. Conference talks, videos or podcasts are even harder to produce and maintain over time (they’re essentially immutable artifacts)
Text is easy to edit and collaborate on. It’s much harder to do this with other medium.
Technical writing is an incredible tool to add value to your team. Onboarding documentation unlocks efficient onboarding, incident runbooks lead to fast mitigations.
Text can be easily distributed and has no fidelity loss when shared (compared to talking to Alice about what Bob told you Charlie said in a meeting that none of you were at).
Writing creates a record, as opposed to “wait, why did we decide on X?”
Writing is applicable almost anywhere when you work as a software engineer: PR descriptions and comments, issue tracker, technical specifications, “one-pager” documents, meeting agendas and notes, Slack, public forums, incident management, communication with management, knowledge sharing in the form of slides or documents, promo packets, peer feedback, long-form documentation, code comments. Given the range of applicability it’s a no-brainer to try to improve as a writer. Small gains in writing efficiency, clarity, speed, or impact will yield massive benefits for your career.

Resources to improve

Ready to improve? Good! Here is a list of resources I’ve come across over the years. Hope you find it useful!

On writing good technical documentation: https://documentation.divio.com/introduction/
Tighten up your prose, write clearly: https://www.goodreads.com/book/show/53343.On_Writing_Well, http://www.plainenglish.co.uk/how-to-write-in-plain-english.html
Become better at documentation and technical design docs: https://developers.google.com/tech-writing
Become better at asking/answering questions on Slack: https://nedbatchelder.com//blog/202009/how_to_be_helpful_online.html, https://dontasktoask.com/
To become better at writing, start writing more! https://bookpub.club/post/to-write-better-you-need-to-develop-a-habit-of-writing–1603298302647x354487348376371200
Lazy (especially when wide!) communication is costly: https://blog.mitchjlee.com/2020/your-writing-style-is-costly
On asking and answering questions (applies to Slack specifically – and PR reviews to some extent): https://jvns.ca/blog/answer-questions-well/, https://jvns.ca/blog/good-questions/
Writing is thinking: https://alistapart.com/article/writing-is-thinking/
On Writing “simple explanations” without sounding condescending: https://jvns.ca/blog/2020/11/15/simple-explanations-without-sounding-condescending/
Comprehensive guide, covering a lot of aspects of writing: https://www.julian.com/guide/write/
Mixed bag of advice from Kurt Vonnegut, one of my favorite authors: https://lithub.com/kurt-vonneguts-greatest-writing-advice/
The Art of Storytelling, by Pixar! This is useful when you want to put together a presentation: https://www.khanacademy.org/computing/pixar/storytelling
The Science of Scientific writing: http://www.inf.fu-berlin.de/lehre/pmo/eng/ScientificWriting.pdf
Write in Plain English: https://www.plainenglish.co.uk/how-to-write-in-plain-english.html
PG on “Writing, briefly”: http://www.paulgraham.com/writing44.html
The day you became a better writer: https://dilbertblog.typepad.com/the_dilbert_blog/2007/06/the_day_you_bec.html
Make your point and get out of the way: https://www.collaborativefund.com/blog/make-your-point-and-get-out-of-the-way/
How to write usefully: http://paulgraham.com/useful.html
Writing as a superpower: https://ckarchive.com/b/p9ueh9hge88w
50 quick hits/tips: https://www.poynter.org/reporting-editing/2006/fifty-writing-tools-quick-list/
13 tips to make any piece of writing better: https://medium.com/an-idea-for-you/13-ways-to-turn-the-next-thing-you-write-into-the-best-thing-youve-written-322005cfddc0
venturehack’s take on business writing: https://venturehacks.com/writing
40 one sentence writing tips: https://joshspector.com/one-sentence-writing-tips/
9 qualities of good writing: https://annhandley.com/9-qualities-of-good-writing
Designer as writer: https://stasaki.com/designer-as-writer/
Writing Tools Learned from The Economist: https://builtbywords.substack.com/p/writing-tools-i-learned-from-the
Patterns in confusing explanations: https://jvns.ca/blog/confusing-explanations
Advice how to structure math explanations (a lot of it relevant to technical writing): https://youtu.be/ojjzXyQCzso?t=500
What I’ve learnt so far about writing research papers: https://tratt.net/laurie/blog/entries/what_ive_learnt_so_far_about_writing_research_papers.html. The conclusion resonates a lot.
Writing non-advice: https://danluu.com/writing-non-advice/
You should write blogs: https://sites.google.com/site/steveyegge2/you-should-write-blogs. Steve Yegge makes good case for writing more in general. Replace “blogs” with “wiki pages” or “docs” in your mind!
Writing Cultures Win: https://founder-fodder.ghost.io/writing-cultures-win/
How to Write More Clearly, Think More Clearly, and Learn Complex Material More Easily (slides): http://www.covingtoninnovations.com/mc/WriteThinkLearn.pdf
Writing for engineers (some really good tips in there!): https://www.heinrichhartmann.com/posts/writing
How to write docs loved by other developers: https://thenewstack.io/an-engineers-best-tips-for-writing-documentation-devs-love
Writing better docs (1-pagers, design docs, postmortems): https://eugeneyan.com/writing/writing-docs-why-what-how/
Don’t think to write, write to think: https://herbertlui.net/dont-think-to-write-write-to-think/
Handbook for Writers: https://saylordotorg.github.io/text_handbook-for-writers/index.html
Why Write: https://bastian.rieck.me/blog/posts/2023/writing_why/
Why Engineers Should Focus on Writing: https://www.yieldcode.blog/post/why-engineers-should-write/
Write About What You Learn: https://addyosmani.com/blog/write-learn/
Software Technical Writing, A Guidebook: https://jamesg.blog/book.pdf

Now, here are some resources which I have not read/vetted yet, but I’ve seen recommended by people I trust:

Clear and Simple as Truth, writing classic prose: https://www.amazon.com/gp/product/0691147434
Skunk & White’s “The Elements of Style” (a classic!): https://www.amazon.com/gp/product/020530902X
Analyzing Prose: https://www.amazon.com/gp/product/0826461905
Prose, the art of non-fiction: https://www.amazon.com/gp/product/0812982150/
Donald Knuth blurring the line between technical writing and coding with the concept of Literate Programing (Amazon link)

Notes from what I’ve read (so you don’t have to)

This section contains notes from articles or books which particularly resonated with me. Expand to read through them.

Write Better Right now (Mary-Kate Mackey)

Notes about "Write Better Right now" (Mary-Kate Mackey)

Below, some notes from reading “Write Better Right now” (Amazon link)

this book is for reluctant writers. I’d put most engineers in this category. Writing is something we have to do. Not something we typically enjoy doing
it’s really odd to me that software engineers love refactoring code but don’t pay as much attention to text. The parallel is obvious: code is information for computers, prose is information for humans. The puzzles encountered when refactoring code are similar to the ones of document editing.
writing isn’t hard. It’s the thinking that’s hard. Writing is a practice to clarify one’s thinking. Yet it’s often seen as something “extra”. For example: design docs. The primary goal is to clarify the design. A secondary goal is to make the design shareable and agreed upon. A nice side-effect: you now have a long-lasting artifact to point to and reflect on when comes perf/promo cycle.
Types of writers: planners, plungers, matchers. I’m a plunger for sure.
Focus for writing: solve your reader’s problem. It starts by defining the problem, and the reader. “What’s in it for me?”
Copy more! As engineers we deconstruct and copy code all the time. Why not do the same with English? Imitate Slack announcement that you like, copy the doc styles that you find effective. Don’t be shy.
As engineers we review code and have a healthy stance: “you are not your code”. I’d like to pilot technical writing review which discusses grammar, writing flaws, etc. It’d be really valuable.\
Word count technique: for every paragraph, write down a condensed count per sentence. Then spot patterns across your document. You may need to vary sentence lengths based on this, to keep the rhythm un-boring. This paragraph is 13-6-16-4-9. Replicate somebody else’s word count to borrow their rhythm
When writing something, have a north star (“cable car sentence” in the book). Fill the blanks: “In my _____ (writing category) about _______ (subject) I am saying that ______ (slant)”. To find the slant of a piece of writing, ask the following questions: what’s this piece of writing about? Why is it being told? How does it connect to the greater world? What’s the point? In one word, what’s this about?
“Shoeboxing” is another technique to spot the theme of a piece: the idea is to label each paragraph with a short label, as if you were to put it in a shoebox and put it in storage.
Edits come in 3 forms:
- “big picture” edit where you check the structure and whether your writing does its job well. Check against the cable-car sentence / slant. Be mindful of multiple interleaved ideas. Simplify.
- “medium” edits are about strengthening verbs (avoid to be/have verbs, minimize adverbs, check for tenses); shoeboxing paragraphs to check their lengths and make sure they follow a logical progression; be on the lookout for too many pronouns. Pay special attention to the first and last sentence of your paragraphs. They’re the “signpost” sentence and the “springboards” that guide readers through your writing. Pay attention to transitions to make sure readers are brought along (transitions can be by opposites, time, place, jump cuts, quotes, questions, facts, point of view, onee liners, observations, compactions summation).
- “close up” edits are the typical typos, spell checking, punctuation, grammar. This is where you take a styleguide and apply it consistently. That’s the most natural kind of “edit” for us engineers. The parallel in code would be checking for extra whitespace, missing dangling commas, indentation problems. Makes your code looks neater, but medium and big picture feedback is far more valuable IMO. We don’t do enough of those.

The Science of Scientific Writing (George D. Gopen and Judith A. Swan)

Notes about "The Science of Scientific Writing" (George D. Gopen and Judith A. Swan)

From The Science of Scientific Writing (George D. Gopen and Judith A. Swan):

Follow a grammatical subject as soon as possible with its verb
Place in the stress position the “new information” you want the reader to emphasize.
Place the person or thing whose “story” a sentence is telling at the beginning of the sentence, in the topic position.
Place appropriate “old information” (material already stated in the discourse) in the topic position for linkage backward and contextualization forward.
Articulate the action of every clause or sentence in its verb.
In general, provide context for your reader before asking that reader to consider anything new.
In general, try to ensure that the relative emphases of the substance coincide with the relative expectations for emphasis raised by the structure.

Another gem from this short paper: “Our best stylists turn out to be our most skillful violators; but in order to carry this off, they must fulfill expectations most of the time, causing the violations to be perceived as exceptional moments, worthy of note”. And finally: “The writing principles we have suggested here make conscious for the writer some of the interpretive clues readers derive from structures. Armed with this awareness, the writer can achieve far greater control (although never complete control) of the reader’s interpretive process. As a concomitant function, the principles simultaneously offer the writer a fresh re-entry to the thought process that produced the science. In real and important ways, the structure of the prose becomes the structure of the scientific argument. Improving either one will improve the other.”

Patterns in confusing explanations (Julia Evans)

Notes about "Patterns in confusing explanations" (Julia Evans)

Julia Evans strikes once again. She wrote this wonderful summary of patterns in confusing explanations and gave some tips to avoid them. Here are the takeaways from my point of view (full article is here):

Have an expert (or somebody who’s familiar with the concept) review your explanation. This avoids key concepts being missed.
Review the assumptions you’re making about your readers; who are you writing for? Where are they starting in terms of understanding?
Test your explanation on somebody who has never been exposed to the concept before. This validates the assumptions you’re making about your readers.
Avoid long-running analogies. Prefer short-lived ones to illustrate a point
Don’t insert pictures to make an explanation “cute”; only insert them if they enhance a point you’re trying to make
Use realistic, working code examples. Not phony ones. And: please please use examples! Examples are crucial for readers to internalize explanations.
Avoid jargon where it’s not needed; use simple words instead
Start concrete, then abstract. Not the opposite (interestingly, 3blue1brown makes a similar case in his advice on how to structure math explanations)
Explanations should read like proofs: don’t add in information without supporting evidence! In other words, don’t be sloppy. Add links to reference docs, prove your point with a working code snippet, link to actual production code, etc.
If you present pitfalls/mistakes, clearly label them as such. If possible in a separate document. Otherwise readers do not know what’s right and what wrong.
Explain why. Even if it’s a reduced, not-so-universal, or even personal “why”. Be honest with why you’re explaining something or using a technology, that will help your readers get in the same frame of mind.