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 …

Make Yourself a Better Writer: Treat Every Document Like a Writing Sample

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, …

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 …

Stump Documents: on Failures to Write Transferable Information

There is a general problem in software, more pronounced in minimalist Agile efforts, of documents that look good at the time of writing, but do a poor job of transferring information. I call these “stump” documents because readers are stumped when they try to learn from them.

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.

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 …

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

(Read part 1 here) A helpful UI is not as rare as a friendly one, because being helpful is more of a technical skill than a personality. Helpful means informative and organized, as well as comfortable to use. I’ll discuss organized and comfortable in a later article. For now, let’s talk about informative.