Save the Semicolon

Have you ever used RoboHelp (or other) snippets? I have experience with RoboHelp, so I’ll stick to that, though I know that other help authoring tools have similar features. I think snippets are great, but (in RoboHelp, at least) they do have their limitations. What’s a snippet? A snippet is a bit of text with [...]

Preserving the writer’s ownership As an editor of technical documentation, I often aim for consistency in language and tone, ruthlessly cutting out any sign of the writer’s personality. I want each help topic, for example, to feel as though it was created by the same person. Whatever tone we choose for the help is the [...]

  Have you ever discussed a change to a document and been given the advice to “just do a find and replace”? As with most jobs, people who don’t write think that writing is easier than it really is. “Just do a find and replace” is one of the most common, and short-sighted, comments I [...]

Putting too much information in a sentence gets across less information. Sentence with A and B gets across A and B. Sentence with A, B, C, D, and F gets across NOTHING. Why, because no one will be able to read it. (Or they won’t want to bother trying.)

A quick tip that I sometimes forget. Complicated ideas are often really hard to write concisely. When I try to compress an idea, I find that I start to lose accuracy, or add ambiguity. The thing that works best for me is to write it exactly how I’d explain it to someone, without worrying about [...]

Have you ever worked on a product that has poor UI copy or design? Of course. What about poor UI copy or design that’s been around a long time and is now the standard way of doing things for that product? When do we force the issue and change it? For professional reasons, I can’t [...]

Have you ever said that something “should” happen, in order to avoid being wrong if it doesn’t? I’ve seen lots of documentation explaining how to do a task, then ending by saying something like: When you click End World, the Doomsday Clock should start. My beef today is with the word “should.” I understand the [...]

As a writer, I know that there are times to break grammatical rules in order to communicate better. Sometimes, for example, that means choosing “who” over “whom,” so as not to remind my readers of their high school principal. But for me, when the rules seem to be at odds with my ear, I usually [...]

A quick tip today about nonbreaking spaces and optional hyphens in Microsoft Word. Let’s jump in. Nonbreaking spaces A nonbreaking space tells Word not to put a line break between a given two words. For example, the following example looks a little funny, because the person’s name is split over a line break: I want [...]

Do you ever find yourself writing a process that gets a bit complicated? Uh, yeah. All the time, right? I’m not talking about NASA flight checks. Frankly, if the process involves more than a straight, linear path, then it gets hard to keep in my head. If you DO have an alligator, go on to Step [...]