Improving as a Technical Writer

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?

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!

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

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.