Recommended reading: Edit with useful comments
Recommended reading for you today: Anatomy of an editing comment.
Author: Sue Arkin
All of the ingredients, none of the recipes
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 […]
Recommended reading: limiting work in progress
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 […]
Whose team are you on?
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. […]
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 reader’s needs, key takeaways and front loading
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 […]
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, […]
Recommended reading: Readable English
Toggle between two versions of each paragraph to see what readable English looks like.
Knowledgebase Ninjas podcast
Gowri Ramkumar at Knowledgebase Ninjas gave me the opportunity to participate in my first ever podcast and talk about my experience in technical writing and the direction Unity Documentation is going. Listen to the episode on their website.
An opinion about not having opinions
“We have the power to hold no opinion about a thing and to not let it upset our state of mind—for things have no natural power to shape our judgments.” Marcus Aurelius, Meditations, 6.52 I’m having my house renovated by a guy called Phil. Phil doesn’t want to turn the house into his vision of […]
Tested Writing 
You must be logged in to post a comment.