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 […]
When breaking a large project into tasks, there are better and worse ways to go about it. A pretty bad start is picking tasks that are the wrong size – they’re still too big, and require further breakdown. So what’s a good size for a task, and how can your own description of a task […]
Cal Newport writes for the New Yorker about Slack’s optimisation of the ills of rapid, unending email communication: “The problem with this trajectory is that no one stopped to ask if it made sense to optimize this style of work in the first place. […] We both love and hate Slack because this company built […]
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 […]
Three articles about limiting work in progress so you can actually get things done: “How finishing what you start makes teams more productive and predictable” by Lucas F. Costa: “Despite the simple mathematics, when some managers see that work is taking longer to finish, they start more work hoping that starting tasks earlier causes them to finish […]
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 […]
After years of grumpily editing old content, I’ve found that many writers – including myself – have a problem meeting the reader’s needs. The average reader needs a concrete outcome like following a process or learning a new concept. Usually, the overall structure of the content matches that need; technical writers have a sort of […]
Tested Writing 
You must be logged in to post a comment.