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 formatting, or even an image, that you put aside to use again. (Microsoft Word has something similar, called the Scrapbook.)

Let’s say you frequently give out your company’s contact info, and you always write it the same way, with the same bits in bold, and the same phrasing:

Want to talk to us? Call TODAY at: blah blah blah blah!

Rather than write that same thing a dozen times (probably introducing some inconsistency along the way), you can save it as a snippet. Then when you want to add that text to a topic, you just drag and drop it. And when you change the snippet, all instances of that text change throughout your help.

There are plenty of resources out there to tell you the steps, but I’ll just mention how I use snippets, and the one major limitation I’ve found while using them.

How I use snippets

I use snippets just about any time I think I’ll repeat myself, but I use them most often for procedural steps.

For example, let’s say that steps one and two for many procedures say:

1. Double-click the app icon.
2. Click the Home button.

From there, the procedures depart. So I write and format steps one and two just the way I want them, then save them as a single snippet. Whenever I need those steps in a topic, I drag and drop them from my snippets to the topic.

Then I know three things:

1. Each time those steps are in the help, they’re exactly the same (saving on translation cost as well as eliminating the possibility for inconsistency of terms).
2. If I want to change one of the steps, I can change the snippet, and all the steps that use the snippet will automatically and immediately update.
3. I can drag the snippet to my Resource Manager, and use it in other RoboHelp projects where it would come in handy. If I didn’t use a resource manager, I could still import the snippet from any project.

By the way, I don’t usually use snippets for contact info (despite my example at the beginning of this post), because I prefer to have a single “contact’ topic that I link to from other places.

But snippets aren’t everything I’d want them to be.

The limitations

One limitation of snippets is that they can be hard to keep track of, or even to remember whether a certain one exists. As far as I know, there’s no good method for organizing them within the Snippets pod. They all just sort of sit there.

But the limitation that bothers me the most is that snippets must always be on a separate line from other items in a topic. I can’t introduce a snippet into a line of text.

Let’s say that I frequently write the following fruity phrase at the end, or in the middle, of a sentence:  including five lemons and a kiwi.

I’d like to add that phrase to end of a sentence, but if it’s a snippet, I can’t. I have to add the snippet on its own line, which ruins what I’m trying to do.

But, limitations aside, I find snippets to be helpful to my work, and I hope they get even easier to use in future releases.

Do you use snippets? Do you have advice, suggestions, or questions about them?

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 one I want every page to have.

So I’m usually not interested in preserving the writer’s voice, the way editors of less technical writing might be. (Though some tech writing does call for an individual voice, it often doesn’t.)

But there is still room to allow the writer to feel ownership of the document.

And why does that matter? Because people work harder, and care more, when they feel ownership. They feel more proud when they recognize a document as their own. And, not least, because the writer might actually know best in some cases how the audience will read the piece.

Editors love to edit

By definition, an editor is critical of writing. If I didn’t think I could improve the written word, then I wouldn’t be doing this in the first place.

And of course, that ability to improve things doesn’t restrict itself to essential problems with a document. It also includes lots of little things that amount to my saying, “I think this sounds better than that.”

But, I have to remind myself that my way isn’t the only way, and isn’t even the best way every time.

If a phrase is unclear, or awkward, or difficult, or illogical (or uses the word “or” too many times), then I jump in. If it’s obviously a different tone from what we’re going for, then I let the writer know.

On the other hand, if the phrase is otherwise ok, but isn’t quite how I would put it, then I try to hold back. I try my best to ask whether this “improvement” would actually make things better for the reader, or if it’s a tweak that would annoy the writer without much benefit to the reader.

Cost/Benefit

In the end, it’s worth weighing. How much benefit to the reader will this change bring, vs. how much of the writer’s ownership are you taking away? It’s worth remember the human writer behind the document, and allowing that writer to write.

Note: Depending on your relationship with the writer, you can have tiers of edits. “Do this,” vs. “What do you think about this,” etc. The key is to let the writer know. I’ll link below to an earlier post of mine that has some interesting suggestions in the comments.

EDIT: Larry Kunz was kind enough to put the same suggestion in the comments to this post, saving you time!

Do you ever have trouble preserving the writer’s ownership? Do you have any tips to share?

Related: How to give proper feedback to a writer

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 hear from non-writers.

Note: I’m not talking about using the Find and Replace tool to go through the instances one-by-one. I’m talking about clicking “replace all” and calling it a day.

Global Find and Replace Breaks Stuff

An example

A company has previously referred to certain app screens as panels, but has decided to start referring to them as “dialog boxes.”

Rather than go through them one by one, they “just do a find and replace.”

Great. All those app screens are now called dialog boxes.

But guess what.

Every instance of the phrase “term panel” (a piece of equipment in telecommunications) was changed to “term dialog box.”

Every mention of the panel of speakers at the big conference was changed to a dialog box of speakers.

Bonus example

There’s a company called Good Company. The marketing VP says that the proper way to write the name is: GOODcompany.

But the product manager can’t remember that, and keeps asking you to edit long documents that ignore the capitalization.

You still with me?

Correct = GOODcompany

Incorrect = goodcompany

“Just do a find and replace.”

After the Find and Replace:

• Find us on the Web at: http://GOODcompany.com (customers think they need to capitalize part of the URL)
• We refer to a filename in a snippet of script that’s case-sensitive. Oops, that script no longer works.
• There are elements in the software that haven’t been updated to the new capitalization yet, but I’ve suddenly told people to click the “GOODcompany button,” when there’s really only a “goodcompany” button.

Sloppy.

Find and replace can screw you up. It’s almost never as simple as other people think it is, regardless of how sure they are that you’re just being difficult.

Find and Replace is sometimes ok

There are some times when I think we can probably (maybe) get away with it:

• When a phone number has changed.
• When a person’s name has changed (as long as the email address has changed as well).
• When we want to update “copyright 2011” to “copyright 2012”.

Otherwise, we just need to patiently explain that making global changes involves either time or risk of error. The boss can decide which choice is best.

Have you found good reasons to use global find and replace? Have you found that others think you can use it more than you can?

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.)

She did good. But was she doing well?

I recently read an online argument about one of the most commonly used, and commonly fought, expressions around: It’s the answer to “how are you?”

“I’m doing good” vs. “I’m doing well.”

[NOTE: I'd also like to defend "I'm good," but others have done it well, so I've pasted a link below.]

But first, a word about usage

Unlike most attacks on pedantry, this one doesn’t rely on usage. That is, usually when defending a new usage (say, “literally” when the speaker means “figuratively”), the defender says that usage is what counts. If a lot of people (or, a lot of the right kinds of people) use a term or phrase, then it becomes ok to use.

But in this case, I’m going to argue that “I’m doing good” is 100% grammatically correct, and the reason to avoid it is because of usage norms.

Why avoid it if it’s grammatically correct? Because a lot of people will think you’re making a grammatical mistake, even though you’re not.

You avoid it because, for social reasons alone, it’s just not accepted.

When I meet the Queen of England, and she says, “Rise, Sir Robert. How ya doing?” I’ll say, “Very well, thank you.” I will not say, “I’m doing good,” even though I know that English allows it. (I’ll also avoid expressions like, “holy cow,” and “coolio” for the same reason.)

I suggest you follow my lead.

But let’s press on.

“I’m doing good” vs. “I’m doing well”

The setup:

Person A: Hello, how are you doing?

Person B: I’m doing good.

Person A (excited at the possibility of pedantry): You mean to say that you do good deeds? Ha! I say, Ha! Why, I was only asking whether you’re well!

Person B: I believe it would be best if we didn’t speak for a decade or three.

–

Straight off the top, I’ll state that Person A does not deserve to converse with humans. Unless you’re truly confused, you’re an instructor, or you enjoy the smell of burnt communication, then it’s best to spend your energy on what the person is saying and not how the person is saying it.

But in this case, Person A is not only insufferable, but also wrong to imply a grammatical misstep.

“I’m doing good” isn’t doing bad

Let’s look at how verbs and adverbs usually work:

“The woman nodded peacefully.”

The word “peacefully” is an adverb, which means that it describes the verb. In other words, “peacefully” describes how the woman nodded, not the woman herself. What was done peacefully? An action. Nodding.

And this idea, that adverbs describe verbs, is what causes some of the problem:

“I’m doing good.”

“Good” is not an adverb. “Good” can be a noun (look at all the good in the world) or an adjective, describing a noun (that was a good show).

But “good” can’t describe a verb like “doing.” For that, we need an adverb, and one adverb we could use is “well.”

Thus speaketh the argument against “I’m doing good.” But there’s a wrinkle. Actually two.

The wrinkles

Wrinkle #1: The English language allows certain verbs to act as “linking verbs.” For example, the verb “was”:

“The show was wonderful.”

The verb “was” is a linking verb. “Wonderful” doesn’t describing the verb “was.” Instead,  it’s an adjective, describing the word “show.” What was wonderful? The show.

There are lots of verbs that can switch from being action verbs to linking verbs.

If you’re a bloodhound, then you smell well. If you’re wearing a bit of perfume (just a bit, mind you), then you smell good.

“Good” is appropriate in the second sentence, because you’re describing something about the person’s smell (a noun), not something about the action of smelling (a verb).

Wrinkle #2: The word “well” can be an adverb or an adjective. This confuses people.

If you scan the horizon carefully, then you look well at the horizon. (Adverb describing something about the action of looking.)

If you have recovered from an illness, then you look well. (Adjective describing you, not the action of looking.)

And finally:

How are you doing? “I’m doing well.”

When someone asks, “how are you doing,” and you answer, “I’m doing well,” you’re using “well” as an adjective, not an adverb. YOU (noun) are doing well (adjective describing the noun).

Both “well” and “good” are adjectives! They’re both legit.

Ambiguity

But what about the ambiguity?

This is the next phase in the argument against saying, “I’m doing good.” It goes like this:

If I say, “I’m doing good,” I could truly mean that I’m doing good deeds. How will we distinguish between doing good deeds vs. being in a state of general well-being?

To which, I reply (haughtily):

If I say, “I’m doing well,” I could mean that I’m doing well AT something (or recovering from illness), rather than meaning that I’m in a state of general well-being.

The truth is that “doing good” and “doing well” are equally ambiguous. Which means that, 99% of the time, they’re not ambiguous at all.

To wrap up

The grammar is correct either way.

And so, if you “correct” the “I’m doing good” people, you should know that you have no grammatical footing. You have only usage and what’s considered to be educated. And by that standard, you may soon have to accept a lot of phrases and definitions that you may not like very much.

See also: Motivated Grammar on “I’m Good”

Disagree? Want to hang me by my toes? Or do you think I’m right?

I’m reading about “Siri,” Apple’s new electronic assistant. You ask it to do things, and it does them.

But I think the marketing writers should have reworked the paragraph shown in the image below:

Have you, as a writer, ever received feedback on a doc that didn’t give you what you need? As an editor or stakeholder, have you ever had to give feedback on a doc, but it didn’t work out as well as you’d hoped?

I think sometimes the problem is that the person giving edits doesn’t really know what the writer needs.

Let’s say someone’s sent along some copy for you to look at. You’d like the writer, Rob, to make some changes.

You send the following email:

The first three paragraphs look great, but let’s change, “Mary and David go around the mulberry bush” to “Mary and David skip around the mulberry bush together”.

Now, this seems like great feedback. It’s concise, precise, and clear.

But Rob sees this and thinks:

“Skip” doesn’t work here because the previous paragraph used “skip” three times and it’s getting old. And we can’t end with “together” because we’ve been asked by Marketing to end with “bush.”

Unfortunately, Rob can’t take your note as a signpost to writing something better, because he has no idea why you’ve chosen “skip,” or chosen to put “together” where you did.

After all, maybe you happen to dislike the word “go.” You don’t really care if the replacement is “skip” “hop” or “roll about with arms akimbo,” but all he knows is that you suggested “skip.”

So he either:

1. Works hard to make the change as requested, lets Marketing know, and rewrites the previous paragraph to get rid of a “skip” or two. Unnecessary work.

2. Makes the change as requested, doesn’t let Marketing know, and doesn’t change the previous paragraph. Marketing is annoyed and quality is lowered.

3. Emails you to explain the problem. Then you have to explain where you’re coming from. Extra work on the writer’s part and on the requester’s part.

4. Some unholy combination of the above.

Here’s a better way to write that original feedback email. It doesn’t have to be eloquent, but it should be clear.

I’d like to avoid using the word “go” in this blurb because the product name is “Go Ahead.” Maybe use “skip”? Also, let’s show that Mary and David are doing this together. I want to make it clear that there’s one bush and they’re both moving around it.

This way, you’ve made a suggestion, but made it clear that it’s just a suggestion. And you’ve explained what you want, while letting the writer choose the actual words. Which, after all, is what you pay him for.

Does this sound like the right way to go about sending feedback? If you’re a writer or requestor, does this make sense to you?

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 it being too long, too wordy, redundant, or anything else. I just get it out on paper.

Then I have something to edit. Once it’s on paper, I can start to kill off the stuff I don’t need and reword the stuff that’s awkward.

This works for me whether it’s one sentence, or a whole paragraph.

Does it work for you?

Usually, people add more words because they think that those words help make the point accurately and completely. And it’s my job to find a way to say the same thing with fewer words.

But not always.

Sometimes, people use more words when fewer would have been MORE complete and get closer to making the actual point.

Here are two tidbits from my daily train ride to and around Melbourne:

FIRST: At the end of the ride, the announcer says something like:

“Please make sure that you haven’t left any personal belongings that you brought with you on the train.”

Every time, they say this “personal belongings” thing, so I assume it’s part of a script.

But they really aren’t saying what they want to say. They don’t want me to remember only my personal belongings, do they? (Not that I’m sure what constitutes “personal belongings” vs. other things I could have brought. But that’s part of the problem.)

They really want me to get anything that I brought on the train.

So if they said to make sure I didn’t leave “anything” (rather than just personal belongings) then they’d not only save words, but make the point they really want to make.

SECOND: This sign lets you know that you could be on video:

My behaviour could be monitored. What about my fashion choices?

In fact, I could be monitored, so why not just say, “you” instead of “your behaviour”? Who is that helping?

And then, why not leave off the “during your journey” part, too?

Isn’t it possible that I’ll be monitored while waiting for the door to close, before my journey starts?

Please understand that I’m not saying that the sign is confusing. I’m saying that the extra words aren’t helping anyone, and in fact are hurting the message by being wrong as well as being wordy.

Do you see stuff like this in your work or daily routine? Does it drive you nuts?

Due to some very silly conversations I’ve had recently, I looked up this post that I had written for another blog a few years ago.

Since it relates tangentially to writing, I thought I’d post it here. If you’ve already read it, well, read it again!

Chaucer with an American accent

Some people seem to think that the English spoken in England is somehow more pure than the version spoken in the US. That it better represents the language that Chaucer or Shakespeare spoke, and is therefore true English, whereas the language spoken in the US has changed into a new version.

If they’re being kind, they’ll say that the new version is no less wonderful. But it is new and different, whereas the England version is pristine. This was Virginia Woolf’s take on the subject, for instance. “American” is great, but it lacks the history of true English.

Absolute, unmitigated nonsense.

Languages aren’t tied to countries, or to land. They’re tied to speakers.

Back in the day, we had a group of English-speakers who were all linguistically descended from Chaucer, let’s say, but who began to live in different physical places.

For example, some lived in Australia, or S. Africa, or the US, or New Zealand, or England.

Now, to be clear, even in England, English wasn’t (and isn’t) a monolith. You can’t swing a dead cat in England without hitting a few seemingly irreconcilable accents, and I assume this was even more true back in the day (before radio and TV and easy travel). But they all spoke some form of English when they decided to live in their different places.

Then time took its toll. All of these people (yes, even those in England) began to develop new slang, new pronunciations, and, to a degree, new syntax. They all did. Their individual versions of the language changed.

None of those groups of people retained the language as it was spoken when they separated. And none of them retained it significantly MORE than any of the rest of them.

For example, the English-speakers who were in the US retained the word “Fall” for the season before winter. People who were in England changed the word they used and started saying “Autumn” instead. People in the US retained the word “diaper,” while those in England changed to “nappy.”

The same thing happened with pronunciations. The people who lived in the US retained more of the pronounced R in words, while those who lived in England tended to lose the R.

This happened lots of times in lots of different ways, in each of the places that the English-speakers lived. Of course, some of the retention happened in England, but so did some of the loss. Some of the retention happened in Australia, but also some of the loss. Etc.

Now we have different accents from each other, and we all have different accents from Shakespeare.

Oh, and we have vastly different accents from Chaucer. Chaucer pronounced words almost completely differently from any living English speaker today. None of his linguistic descendants who chose to live one place or another have any claim to speak his language.

So I feel a small twinge when I see movies like “Shakespeare in Love,” in which an American actress (the extremely lovely Gwyneth P.) puts on an English accent in order to be more authentic.

Or when I hear people complain about Americans retaining their accents when playing Robin Hood.

For Shakespeare, Robin Hood, Chaucer, or even Queen Elisabeth I, a modern English accent is no more authentic than a modern American accent. Either way is wrong, in a sense, and either way would sound wrong to Chaucer or Shakespeare or the Virgin Queen herself.

Put another way, they’re both equally right, because Shakespeare is just as likely to be familiar with Gwyneth’s real accent as he is to be with her English co-star’s.

I’d like to see a movie, set in England several hundred years ago, with American accents. Or even American and British and Australian and more. They could represent the different accents that one would have found traveling around England at the time.

Of course, the ignorati would scream about how it’s not authentic, because Americans didn’t live in England in 1452. But we’d know better.