How technical writers can help engineers overcome fear of writing

A technical writer shares ways to work with software engineers who don’t like writing documentation.

As a technical writer, I present information to users. Instructions and tutorials need to be clear, concise, and painless. If my writing is opaque, support workers feel the brunt of it through service tickets and angry emails.

When I pivoted from software engineering to technical writing, I knew this. I expected bulky notes of information and half-formed thoughts in diagrams. I love this aspect of the work because it feels like a puzzle. How do I transform an engineer’s freeform design brief into a comprehensible guide? How do I document an API that always changes?

What I didn’t expect is how much of the work is interpersonal management. Day to day work includes writing, but it also includes communication with others. I pester developers for release notes, message them with clarification questions, and critique their docs-as-code pull requests.

I’ve long practiced critique as a neutral action. By borrowing the framework of blameless retrospectives, no person is at fault. Critiques are a collaborative discussion rather than an argument.

So why were my engineers hesitant to share their writing with me?

I didn’t understand, so I dug deeper. I pushed in conversations to diagnose why my subject matter experts were slow or outright refused to write. I asked engineers, product owners, and QA. I talked with other technical writers. I needed to know why. If experts don’t provide content, I can’t do my job, and my users suffer.

I got a variety of answers, but the most common one surprised me: fear.

Why writing makes us anxious

Tech writers, despite our excitement to listen and greed for content (more, give us more, we want all the details), represent a source of stress in many engineers’ lives: language classes.

Language is not only subjective and ever-evolving, it’s also judged based on further subjective rulesets. By its nature, language can never be truly correct. There is no right or wrong answer.

If an engineer learns to fear making mistakes when writing, whether in school or previous work experience, writing becomes a source of stress. This is called “writing anxiety”, or “writing apprehension”, and is extremely common even among professional writers.

Each person has history with writing that influences their daily life as a professional. Some common causes of writing anxiety, besides the aforementioned unclear grading rubrics, include:

• previous bad experiences with readers (overly harsh critiques, overly demanding, etc.)
• limited resources (time, energy, support, ability)
• conflicting priorities
• fear of judgement from coworkers
• lack of clear, correct content to write

The listed reasons are pretty self-explanatory. Overly harsh critiques or demands make writing joyless. Limited resources like time and energy, especially during a hectic product cycle, don’t allow an engineer to sit down and consider what they’ve made.

However, I’d like to add additional causes:

• lack of confidence in written language, especially when writing in a non-native language
• fear of discriminatory critiques, especially when marginalized people submit content

Cause #1: Lack of confidence in written language (especially when writing in a non-native language)

I write in English and communicate in no other languages. It’s a sign of my white American privilege (or lack of education) that I only know English. Many Americans joke that English is full of rules slammed together from other languages. It seems fake that saying “buffalo” 8 times is a real sentence somehow??

For non-native English speakers, it’s understandably intimidating to submit written content if they don’t have confidence in it. While search engines present lots of technical writing resources for non-native English speakers, very few are targeted towards technical writers reviewing their work. I’d like to add my own personal experiences, and suggestions from non-native English speakers.

Before I continue:

• Non-native English speakers are not a monolith. Many speak and write English “better” than native English speakers. In the context of these suggestions, I’m focusing on non-native English speakers who do not write professionally.
• Writing quality in English is heavily based in white supremacy. To read more about anti-racism in technical writing, I highly recommend reading the CCCC Black Technical and Professional Communication Position Statement with Resource Guide.

How to better review content from non-native English speakers

First, Adriana Romero-Olivares did an incredible job with her article “Reviewers, don’t be rude to nonnative English speakers”. As a scientist, she faced significant challenges in publishing her work due to racist or condescending reviewers. She lays out multiple rules reviewers should follow regardless of their field. Her main points are:

1. “[D]o not make assumptions about the quality of a paper based on the authors’ names and affiliations.”
2. “You are a reviewer — not an editor. Focus on the research. If the English is so poor you cannot review the paper or provide feedback on the science, tell the editor so that they can decide how to proceed.”
3. “If the paper is not written in sound English, it is OK to correct grammatical errors and help improve the writing. But remember that you are not a martyr or the savior of people who did not grow up speaking English. Be kind.”

From my personal experience, I’ve found the following strategies helpful:

1. When asking about something, explain why you’re confused. (Example: “In the diagram, this box is labeled Service. What kind of service is it?”)
2. Describe your expectations. As technical writers, we don’t require final drafts of information, but that may not be clear to someone with writing anxiety.
3. If an engineer isn’t comfortable writing content, ask them to explain it to you verbally, and transcribe what they say. Send them the transcription so they can correct any inaccuracies.
4. Provide templates and examples to reduce the need for content formatting. This allows the engineer to focus on the writing, not the presentation.

Cause #2: Fear of discriminatory critiques, especially when marginalized people submit content

Because marginalized people are heavily penalized for the quality of their work regardless of its actual quality, critiques become risky. Discrimination and bias are real influences in technical writing reviews. It’s up to us as technical writers to address our internal biases before reviewing others’ work.

As a white person, I cannot and should not decide what is or is not racist. Instead, I’ve listed resources I loved while unlearning racism and bias in tech writing. While heavily centered around academic writing and review, the information also applies to industry professionals.

• “Inclusive and antiracist writing overview”, Simon Fraser University
• “Programmatic Efforts to Redress Anti-Blackness in Technical and Professional Writing” by Jennifer Sano-Franchini, Ph.D., West Virginia University
• “An Anti-Racist Reviewing Heuristic” by Lauren E. Cagle & Emma J. Rose
• “Anti-racism and Anti-oppression”, University of Maryland — Baltimore

I once again struggled to find resources focused on technical writers reviewing others’ content.

This doesn’t mean we shouldn’t improve.

Relying solely on our education, academic or social, means relying on ingrained behaviors that uphold oppression. We have a unique responsibility to expand our understanding of language in our industries, to expand the possibilities of how we talk to our users, to expand the dynamics between writers and engineers. We cannot allow comfort in our expertise to become complacency in cultural literacy.

About the Author

Jess Schalz (she/they) is a software engineer-turned-technical writer. She has a terrible cat named Sudo, and the two of them live in Minneapolis, MN.