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.
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.
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.
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 ,
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](LINK).
Not this ❌:
You can learn more about database indexing [here](LINK).
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.
SOCIAL SHARE CARD GENERATOR