Embrace the suck, writers’ edition

In a post titled Find It in the Edit, I mentioned that your first draft is going to suck, and that seven drafts into the writing process is halfway there. I was making a point about the importance of editing. But I should have made another point: “The suck is normal. It’s almost requisite. Embrace […]

Consistency, punctuation and the oxford comma

One of the most popular posts on this blog is the one where I suggest foregoing consistency when using (or not) the oxford comma in UI. Did I really suggest punctuating inconsistently? Yes. Yes, I did. Readers don’t care about your company’s consistency; they care about clarity. With vocabulary, being inconsistent is a great way […]

Users don’t always ask the right question

Inspired by this post about the XY Problem, let’s talk about how users can approach documentation from a totally unhelpful angle. The gist of the XY Problem is that “I was doing X and it’s not working” is not the same as “I was trying to solve Y; was X the right way to do […]

Find it in the edit

Three little rules: Your first draft is not worth the keyboard it was typed on. If you’re seven rewrites in, you’re probably halfway there. If you can’t imagine what good another pass could do, you’re not done – you’re ready for the first review. Which is the long way of saying: learn to edit, not […]

The dos and don’ts of writing samples

In no particular order, here are my recommendations for writing samples for those of you applying for a tech writing job. And yes, you need writing samples. Purpose The purpose of writing samples is to prove you have technical writing skills, not that you’ve held down a job. So when you pick or write samples, […]

Writing from the ground up

Writing begins with awareness of the single word, then moves up. What can a word mean, and what does it actually mean in its current context? Does the sentence make its point as clearly as possible? Does the paragraph come together as a single point? Is it in the right place Does the whole document tell […]

Redefine your audience through the gaps

When users find a gap in your documentation – some jump from A to C that gets negative feedback – don’t just fix it. Ask yourself how it got there. Gaps happen because: Someone didn’t think users needed the topic. This demonstrates a misunderstanding of the audience. someone didn’t think about the topic at all. […]