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 […]
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 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 […]
That dreadful moment (hour? day?) when the words won’t come. We think of writer’s block as something that is stopping a well formed image from settling into the right words. But in reality, a writer’s block happens when our mental image is a little hazy and abstract. We can’t put it into words because words […]
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 […]
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. […]
As a technical writer, one of the most important questions you can ask yourself is “what are the default values of the choices a user can make, and why”. For example, if an option is disabled by default, what does that tell you about the average user and their workflow? Are you trying to protect […]
The only way to improve, the internet keeps telling us, is to push yourself past your comfort zone so that you’re always learning new things. Writing day in and day out, however, can mean you start to churn out documents on semi-automatic, settling for your current skill level and never improving. In fact, some of your skills, […]
Here’s a quick writing tip for user manuals: don’t add your images to the manual until you’re done writing your text. This has two advantages. The first is that when you add images one at a time over the long course of writing a manual, it’s easy to overdo it. When you add them all […]
Tested Writing 