Writing from the ground up

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 …

Quick writing tip: What’s the default, and why?

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 …

Quick Writing Tip: Don’t Add Images Until the Text is Done

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 …

Lessons I Learned as a Tester, 3: Chinese Whispers Are no Basis for Testing

Written in collaboration with Efrat Wurzel The basic premise of QA is that developers – being human – make mistakes; but too many testers think that developer mistakes are limited to the code they write. The truth is that developers can misunderstand the spec, forget a part of it, never notice that a spec is …

No Spec? No Problem: Testing When Nothing’s Written Down

Written in collaboration with Efrat Wurzel Got a new product to test, and the most documentation anyone can provide is an e-mail saying “wouldn’t it be cool if we got drunk and then wrote some code”? Don’t worry – testing without a spec is not quite the disaster you were expecting. Using some exploratory testing …

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.

Lessons I Learned as a Tester: Don’t Let Developers Go Crazy With Testing Instructions

When asked to provide testing instructions for a new feature or bug fix, there are three types of developers: some are surgically precise, some are fairly precise while erring towards caution, and some give the widest set of instructions they can get away with, usually in an effort to protect themselves against accusations of insufficient …

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.