“What do all the words mean?” Asking that is a very powerful way to start working on a document that Product or Engineering requested, but for which they provided little more than a headline: “We need a document explaining how to cook fish in an office microwave”. What do all the words mean? Then continue […]
Whether your colleagues just got laid off or are worried they’ll be next, there are ways you can help – even if you don’t have a job to offer them. All of these things can help people feel prepared and in control, and can reduce anxiety. That’s about all you can do, since you can’t […]
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 […]
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 […]
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 […]
Recommended reading for you today: Anatomy of an editing comment.
This is an egg. This is an onion. Now go make an onion omelette. There is a flavour of documentation I call “All of the ingredients, none of the recipes”. I’m not sure I invented the phrase, but I’m sure I like it. It refers to the sort of documentation that tells you all the […]
As an IC, your main structure at work is a team of other ICs. As a manager, you manage a team of ICs, but are yourself working alongside other managers. This means you and your ICs are, in effect, on two different teams. This blew my mind a little when it first happened to me. […]
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 […]
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, […]
Tested Writing 
You must be logged in to post a comment.