Don’t Dumb it Down; Layer it Up – Writing Tips for Engineers

When explaining complicated ideas, your goal shouldn’t be to dumb things down – you’re here to teach, not to help people avoid learning. But the best way to teach is not to start at the expert level and hope your readers follow along – it’s to start at the bottom and layer it up. Give …

Talking to Users: Polite, Friendly and Helpful UI (Part 1)

Because I am both a technical writer and a software tester, one of my pet peeves is an interface that falls apart when it needs to communicate anything to the user. On every project I see code instead of text, poor grammar and spelling, ALL CAPS, odd choices of punctuation marks and a great many …

How to Get From Zero to User Manual

One of the challenges of project work is that you have to get into things quickly and without much help – in many places, people will have neither the time nor the inclination to teach you. Remember that if you want to write about how something works, you have to understand the why of it …

TMI: The Expert Fallacy

The natural assumption of most software companies is that an application intended for experts in the field doesn’t need to explain anything beyond the interface. The user is supposed to know the work-flow and terms at least as well as the manual’s writer. But the reality is that many people are trained in the field …

How to Make Your Texts Easier to Scan

Scanning is the quickest way to get through reading material: glance at it just long enough to find the bit you’re interested in. It’s a big time-saver for readers and they’ll thank you for making your text as easy to scan as possible. The readers’ scanning speed is determined by your writing and formatting decisions. …