The Oxford comma, or serial comma, is the comma that sometimes appears in a list before the last “and”, “or” and so on. It has somehow become a battleground of punctuation, because some people always use it while others never do, and emotions run high.
Category Archives: Technical Writing
Writing for How-To Videos, Part 1: Basic Considerations for Scripts
Two notes before we begin: first, this article is about software how-to videos, not instructional videos that explain a subject or your business plan. Second, this is the first article of two. I’ll present some basic considerations in this one, and focus on the content of the scripts in the second one.
Questions to Ask Yourself Before Writing an FAQ
Some technical writers hate FAQs. I rather enjoy them, because they’re the only bit of technical writing most people will ever bother reading. But they’re not always an easy thing to write; since FAQs are never full explanations of the application or website, deciding what to put in them can be difficult.
Screen-Cap Tips for Beginners
If you’re starting out in technical writing, here are some things to consider when adding screen-caps to user manuals and training guides.
Communicating an Existing Interface to a New Designer
When a new designer joins an existing project, the temptation to show the designer the interface rather than the spec is hard to resist, especially if the two are not very similar. The problem is that some information that was in the spec is very important to the designer, but will often not be communicated …
Continue reading “Communicating an Existing Interface to a New Designer”
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 …
Continue reading “Don’t Dumb it Down; Layer it Up – Writing Tips for Engineers”
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 …
Continue reading “Talking to Users: Polite, Friendly and Helpful UI (Part 1)”
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. …