| HN Mirror

Being a great tech writer is pretty ambitious. Maybe start with wanting to be a competent one.

The way I learned was by being a junior writer at Apple surrounded by much better writers and professional editors. They assigned me what they thought I could do. They reviewed my work and taught me to make it better. The editors were generous enough to not only correct my mistakes but teach me why they were mistakes.

Not everyone has that opportunity, obviously.

Write a lot. Seek good feedback.

Good feedback tells you whether the reader learned what you meant to teach. It tells you how hard it was for the reader to learn it, and where the text was confusing or hard to follow or just plain hard to read.

The best-quality reviews I've ever gotten were from professional technical editors--no surprise, since that's their whole job! Still, you can do pretty well if you can find a smart, literate person who is comfortable telling you clearly what works and what doesn't in your work. What you need to know is whether your work engages the reader, is easy to read, is clear, and conveys the knowledge you intend.

You'll have to write and write and write. Write a draft and get it reviewed. Fix its weaknesses and get it reviewed again. Repeat until you just can't make it any clearer, simpler, and more successful.

Write about different subjects, then take those drafts through the review process.

Review your own writing, but not too many times, and leave enough time between readings. If you try to review too soon after you've written a draft, or too many times, then you'll miss a lot of mistakes because you'll see what you expect to see instead of what's actually on the page. The right limits might be different for different people; for me it's best to wait at least a day after I've written something or previously reviewed it.

Oh, and I should add: print your drafts and mark them up with a red pen. It's a different experience from editing and correcting text on a screen, and I find it helpful in ways that differ from online editing. If you want to try it then you might like to consult this cheat sheet:

https://amstp.northwestern.edu/documents/proofreading-marks-...

Read about writing. The Elements of Style is dated, but still good. The same goes for Words Into Type. The Chicago Manual of Style is a huge tome, but is a standard for good reason. Every Page is Page One is helpful, especially for writing documentation that winds up on the web.

Publications departments generally supplement references like these with in-house style guides. You might see if you can get your hands on one or two of these. Their main purpose is generally to teach new writers how to sound like the particular pubs department, but they also encode stylistic decisions that are intended to keep the text clear and accessible. You might not want to slavishly imitate any specific house style, but reading a few guides and thinking about what they're trying to accomplish can help you think critically about your work and develop your own style.

Apple's current style guide is here:

https://support.apple.com/guide/applestyleguide/about-the-gu...

Wiley and Sons has one here:

https://authorservices.wiley.com/asset/photos/House_style_gu...

Cisco's style guide is here:

https://img1.wsimg.com/blobby/go/31485ed6-9671-47cc-b0c0-353...

If you can think of technical publications that you admire, see if you can find the style guide that governs them. Read it and think about why they're giving the advice they do. Cherry pick the good thinking and apply it to your work.

Take a look at Diátaxis, which provides a nice structured way to think about the different kinds of tech writing and their different purposes.

https://diataxis.fr/

If you think of a question I didn't answer, ask. If I know the answer or have an idea how to find it, I'll let you know.