Putting the "tech" in technical editing

Putting the "tech" in technical editing

What does it mean to understand complex technical topics at a high level?

I have a broad and shallow understanding of technology. I knew this was a good thing but I couldn't articulate it until I came across a requirement for a tech editing role: “We'd like someone who can understand complex technical topics at a high level.” (Thanks Draft.dev for this description.)

The February 2022 edition of the Write the Docs newsletter concluded that while “domain knowledge trumps all”, you need “just enough” knowledge to get your work done. I think this holds true for editing as well as writing. As a technical editor, you do need domain knowledge. You need to understand the subject matter to be able to add value. But you don't always need a deep knowledge—and sometimes, to really add value, you need an awareness of how that subject matter fits within a broader domain.

Editing excellence through domain awareness

Mark Baker talks about a state beyond domain knowledge in a post from 2016, Writing Excellence Through Domain Awareness.

Domain awareness is about recognizing "which concepts, ideas, and principles belong uniquely to that domain" and further, what sits around it—knowing its place in the universe. Understanding the space outside a domain gives you the ability to add value, especially in writing about technology. The landscape is vast!

Domain awareness means I can advocate for the reader and polish writing to be clear and simple - especially around a complex topic.

The IPEd 2021 Survey showed that 92% of members had tertiary education. “Tertiary qualifications, regardless of whether they are specifically in editing or not, show that editors have skills in communication, critical thinking and judgment, as well as an understanding of broader cultural contexts.”

Building domain awareness

How does a tech writer upskill in tech? By getting their hands dirty. I recently came across a Google job description outlining different ways a candidate may have gained domain knowledge:

"Experience in technologies (software or hardware systems) by investigation, direct experimentation (for example, reading or running code), and interactions with Subject Matter Experts."—Google

How did I come to a place of domain awareness? All of the above, plus time. I think it’s a combination of working and lived experience (14 years a tech writer), and a steady diet of consuming industry content (I read a lot!). This has enabled me to edit content about a variety of topics these past couple of months sweeping across:

  • Core mergers and certification for an open source CMS.
  • Blockchain, validators, and indexing for a web3 client.
  • Async PHP, non-blocking and event-driven architecture for a digital agency.
  • User research and testing, website IA, a11y, and human-centered design for a UX group.
  • Devops, automated testing, and shifting-left for the internal IT team of a major corporation.

How domain awareness makes me a good editor

Writing about tech can get really noun-heavy. For writing to be clear, it’s crucial to identify actors in a sentence, and what is being acted upon. My understanding of tech stacks, processes, and workflows means I can better identify the subject of a sentence, and parse the verbs, nouns, and adjectives.

I may not be able to code, but I do understand how technology fits together and works within a broader ecosystem. In addition, my personal experience brings an authentic and valuable perspective to the tech writing I edit.


Image credits: Brain image by Milad Fakurian on Unsplash.