I've been interviewing technical writers. What stands out about amazing candidates is that they spend surprisingly little time on the details. This surprises me and had me reflect that I look for, or rather, what makes a good technical writer.
I think the assumption is that a good technical writer is made in the details. You want detailed, complete, and accurate documentation. This is what a lot of candidates focuses on, how they approach technical writing to make sure they understand the complete product use cases and accurately regurgitate that information on a page.
If this is a candidate's focus, to me, that's a giant red flag 🚩
As a technical writer, I don't think our value is in the ability to accurately recount the technical demos given to us by engineers. It's in structuring and filtering information to make it more accessible.
Take a look at the R manual, for example:
Complete? *Yes! *
Detailed? Yes!
Accurate? Definitely!
Would I, or anyone learning R read this thing? Well, this part is debatable.
It's a long running joke among technical writers that if your documentation requires a "how to read" section, you've done it wrong.
Technical writing serves a clear purpose, making information accessible. Getting accurate information is the easy part, any engineer can do a better job than you, because you didn't build the feature.
As a technical writer, your job is to abstract, structure, and enhance information to make it easier to access.
Once more for emphasis:
Your job is to abstract, structure, and enhance information to make it easier to access.
The devil is not in the details. The information is not novel. What's novel is the presentation and structure that lets a developer find what they need in 5 minutes, not 50.
Here's what I look for in a technical writer
Start with the journey
Good docs flow from most general information to least, commonly needed workflows to power moves, and low resolution to high resolution.
Give me only the information I need at a given stage in my learning process. Don't overwhelm me. Keep the examples simple, even if I'm missing details.
Quick wins
Your docs serve 0 purpose unless someone reads them. To encourage them, like a benevolent teacher, you need to give them confidence that you're leading them somewhere.
Quick wins encourage the readers to keep exploring. Attention span and patience are finite, you gotta fight for it.
Information hierarchy
Most important information first. I need to scan the start of a page to know if the page contains the information I'm looking for. I need to scan the start of a paragraph to know if the details are relevant.
Take this paragraph for example:
Security is important in development. That's why you should take care to protect secrets. Secrets should be safely stored as a environment variable in a vault. You can find vaults under **settings** > **security** > **vault**. Don't share this with anyone!
Now the same information:
Store secrets as environment variables in vaults by navigating to **settings** > **security** > **vault**. Your secrets should never be shared. You must ensure data privacy, sharing secrets can compromise security during development.
Same information, one is easier to read than others.
Know the reader
Some products expect expert readers. Some products expect novice readers.
Take a look at the getting started guide for PlanetScale and getting started guide for Supabase,
One focuses on high-level information to help senior devs make decisions on the tech stack, one focuses on quick wins and short examples to help you get your foot in the door.
Accessible links (bonus)
One thing I've started to look for is accessible links. How many times have you seen an embedded link like this.
Your links should be complete and have full context for it to be more accessible. While some can tell what a link does from context, those using accessibility tools might find it annoying to figure out where a link leads.
Do this ✅:
You can learn more about database indexing in our documentation.
Not this ❌:
You can learn more about database indexing here.
Bottom line
I care about accuracy in docs. If this is all I had to care about, I'd just make everyone read API references.
Fact of the matter is, I need to help a developer go from 0 to 1, but also experts to scale from 1K to 1M. You do this by abstracting and structuring information, so focus on your ability to do this on your next interview.
Top comments (1)
Thank you for catching typos in my brain dump ❤️