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, …
Continue reading “Make Yourself a Better Writer: Treat Every Document Like a Writing Sample”
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 …
Continue reading “Quick Writing Tip: Don’t Add Images Until the Text is Done”
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. The main difference between stump and transferable documents …
Continue reading “Stump Documents: on Failures to Write Transferable Information”
You might say I learned this lesson as a technical writer, too. If you’re publishing release notes (and you really should), it’s for things that have gone through QA. Ask your testers to provide the first draft of the release notes, then ask them to verify the final draft. This has two benefits: 1. If …
These questions are for experienced candidates, not aspiring writers, and are meant to reveal general attitudes and methods. You want to see how people think, and how they act and react to other writers. Question one: tell me about a style guide decision you disagree with. The idea isn’t to argue the point with them; …
Continue reading “Five Questions for Technical Writing Interviews”
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. I recommend letting go of any emotional attachment to the …
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. Order of Business …
Continue reading “Writing for How-To Videos, Part 1: Basic Considerations for Scripts”
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. What Goes in …
Continue reading “Questions to Ask Yourself Before Writing an FAQ”
If you’re starting out in technical writing, here are some things to consider when adding screen-caps to user manuals and training guides. 1. Screen-caps should have data in the fields, to help people understand the window. If you want to show the window as it is when first opened, which is mostly empty, add a …
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”
Tested Writing 
You must be logged in to post a comment.