If you’ve installed RoboHelp 11, then you may have noticed that you can’t just “pin” its icon to the taskbar at the bottom of your screen.

But… I MUST have it there. So here’s the workaround that a colleague found:

1. If you don’t already have a RoboHelp shortcut on your desktop, create one. (That is, right-click the RoboHelp icon and choose Create shortcut.)
2. Name the shortcut anything that doesn’t have the word “help” in it. I don’t know why.
3. Drag the shortcut to the taskbar.
4. Enjoy your life!

If you’re at all interested in language, or in English, then you already know that words change meaning. And not only do they change meaning, but sometimes they’re coined to mean something other than what you might expect. For example, if someone calls you a “mouth-breather,” then you should know that you’re being insulted. I’m sorry to be the one to tell you, but someone thinks that you’re stupid.

Now, there are probably extremely bright people who momentarily, routinely, or permanently breathe through their mouths. But that makes no difference, because “mouth-breather” doesn’t mean, “a person who is breathing through the mouth.” It means, “a stupid person.”

It would be silly to say that people who use that insult are using it wrong. Or to say that they’re confused about the meaning of mouth, breather, or the myriad ways that a person can come to breath through the mouth. It was coined to mean “stupid,” and it’s meant “stupid” ever since.

Let’s get to the point

Which, of course, brings us to Israel. Ok, not exactly, but there’s a silly bit of nonsense that is cropping up more and more now that Israel is more and more in the news. Today I read the following comment about the word anti-Semitic:

Could we get the terminology right? “Semitic” has two common definitions (1- A language group in the Afro-Asiatic language family that includes Hebrew and Arabic. 2- description of Middle East peoples that trace their origin from the biblical Noah and his son Shem; these include Jews and Arabs.). So “anti-Semitism” should properly refer more to anti-Arabism than to anti-Jewishness, as only about 20% of Jews are of Semitic origins while nearly all Palestinians would be Semites.

This specious reasoning is usually followed by some kind of accusation that Jews have somehow co-opted the term and stolen it from the proper Semitic peoples. But “anti-Semite” was popularized by a guy who was against Jews; he coined it to mean people who are against Jews, and it’s meant the same thing ever since. So they should blame him.

In short, it’s a bad idea to break apart a word and then assume that it means the sum of its parts. Go tell people to stop doing it!

Several years ago, I interviewed with Google for a tech comm position. I got as far as a phone interview. Everyone told me that Google only hires people who wrote a book on the subject, or invented something great. It’s not enough to be merely a good writer.

In some ways, that was consoling. But in a more important way, it made me realize that my resume at the time wasn’t ever going to make me a “must hire”. I could get a job, of course, but I certainly wasn’t standing out from all the other “tech writer with x years’ experience” people.

Those people? They’re all tech writers. But where’s the passion? Where’s the thing that the employer is excited about? Where’s the thing that looks impressive on the company’s “welcome aboard” email?

Here’s what I did:

• I started reading a lot of blogs and research about tech writing. I can’t put that reading on my resume, but it led to some of the stuff below. And I left comments on people’s web sites as well, which sometimes starts really interesting and helpful conversations.
• I created this web site. Yes, the truth has come out, ladies and gentlemen. Save the Semicolon is nothing more than a callous attempt at proving that I’m serious, passionate, and dedicated to my chosen profession. Of course, this site also helps me connect to people, learn from people, and share what I know. All good reasons to have a website.

What to write about? Write about the research that you’ve read. Write about something that another blog has made you think about. And of course, write about your own experience. If you don’t think you can maintain a web site, then ask to write a guest post on someone else’s site. Lots of people are looking for material, and they’d be happy to publish yours.

Take note: Your experience is valuable, regardless of how much you have. For example, this post about being an intern always gets a lot of interest. There are people out there who want to hear what you’ve learned. Every time I’ve posted something that I thought was too basic, or too obvious, or too personal, someone has told me that it helped them. Sometimes it’s nice for people to read what they already know. Validation is valuable.

• I created a twitter account and started tweeting about tech comm. I have to admit that my Twitter posts are hit and miss and I’ve slowed down (a LOT) in the last few years. But I can always pick it up again, and I have a body of tweets that show that I’m part of a community of tech writers. I’m not just some guy cashing a paycheck in a field that I fell into or am trying out.

What to tweet about? Tweet about other people’s blog posts. Tweet about experiences that you had. Link to pages that might be interesting to people.

• I maintained my membership to the professional societies. A person who is a member of a professional society (like STC, for tech writers) is a person who’s taking it seriously.
• I gave a presentation at the STC annual summit. Suddenly, I’m an expert. And how did I know that they were accepting proposals for presentations? I probably read it on a blog or saw a tweet about it.

The great thing about these things is that they actually make me a better tech writer. For example, doing research for a blog post or tweet forces me to stay up-to-date with what’s happening in tech comm. It’s good for me even when I’m not looking for a job.

I’m sure that there are plenty of other ideas out there, so please let me know if you have one! How can people get noticed?

The question is almost a cliche: How do you get a job without experience and how do you get experience without a job? Well, for tech writers, the answer might be simpler than you think, because there are lots of software projects out there that need writing help from anyone they can get.

They won’t pay you. Let’s get that out of the way right now. But you can add a line to your resume and a project to your portfolio while actually helping people. And when you’re interviewing for a job, you can point out that you’re actually doing something with your time other than going on job interviews. Not only are you working, but you’re showing that you take being a tech writer seriously.

Note: This is different from doing free work for regular companies. Normally, if someone asks you to work for free (or for “experience” or “exposure”) then the answer is no. But open source is different. It’s the community coming together to create something, not a tight-fisted company trying to rip-off young writers.

As a guy who’s recently spent hours looking at resumes, I can tell you that some volunteer work shows that you know what the job is about and are for real. You’re not one of those people thinking, “hey, maybe tech writing could be for me.” Those people are a risk to hire. I don’t want to train people only to find that they don’t really like tech writing after all!

So have I convinced you? Here are a couple of places to start:

• http://sourceforge.net/p/forge/helpwanted/documenters/
• http://www.webkit.org/projects/documentation/

One more thought

Though I’ve never tried it, this idea makes sense to me: Find practically any local charity with a poorly-written Web page (or other written material) and offer to write for them for free. I’ve seen a lot of abysmal writing on sites like that, and I’ll bet they’d be happy to hear from you. Bonus: there’s probably a tax break in it for you and if you do a good job, maybe some recognition and paid work down the line.

Has anyone out there done any open source work? How did it go?

Image courtesy of Master isolated images / FreeDigitalPhotos.net

.
Recently, I went through the process of hiring a tech writer. My boss, who is not a tech writer, sat in some of the interviews and always said the same thing to the prospective writers: “For this job, weâ€ll need someone who will actually install and operate the software that he or she is writing about.”

And each time he said it, I thought, “well, duh.”

But my boss knows something that I shouldnâ€t be surprised about. Some writers donâ€t bother. Some writers donâ€t follow their own steps as they write (or after theyâ€ve finished writing). Instead, they write from memory or, even worse, from someone elseâ€s memory. Sometimes they write from a spec sheet.

Thatâ€s a really bad idea.

First of all, it makes for a less helpful experience for your audience. More on that below. But also, it lowers your value as a professional. Weâ€re supposed to be the people who think like the audience. We can see things from a different perspective and catch problems that other people donâ€t see. If a writer is merely someone who take specs and puts them in a different format, then you may as well hire an intern. Sometimes you have no choice but to write from spec (like if the product hasnâ€t been created yet and thereâ€s no time in the schedule for writing later). But the cold fact is that the end result is worse when we donâ€t do it ourselves.

Rather than rail about it, Iâ€ll just give you a recent example of something that was written well enough, but was still a bad experience for me.

The example

I needed to temporarily remove a little program called Silverlight from my computer. I checked the help, and on a good note, there WAS some. I just needed to delete a few files. (There was also a link to a separate page on how to “uninstall” the files, which amounts to “find them and delete them.”)

The writer put the files in order of the file type. First you delete all the siliverlight files, and then you delete the WPFE files. Now, it doesnâ€t really matter which ones you delete first, but most people would start at the top and go down.

Hereâ€s a screen shot of the page:

So whatâ€s wrong? Well, have a look at where the files are actually located. The first one is in the “Internet Plug-ins” folder. The second and third are in the “Receipts” folder. Fine so far.

But wait! The fourth file is in the “Internet Plug-ins” folder. Wasnâ€t I just there? And then, for the cherry on top, the fifth one is back in the “Receipts” folder!

That means that to delete files in two folders, Iâ€ve just navigated to a folder FOUR TIMES!

There is no way that a writer went through that process without realizing that something was wrong. So my guess? The writer didnâ€t bother going through the process.

And this isnâ€t even really a process! Itâ€s just a list of files to delete. Imagine all the little gotchas that can happen when you have 5 or 10 steps to follow. I guarantee that there will be little things that you donâ€t know about until you do it yourself,

To put it more poetically: You canâ€t lead your audience through your product by standing behind them and pointing. You have to go first.

I know, there’s nothing original about saying that writers shouldn’t use clichés. This post is therefore a cliché in itself.

Still, I wanted to.

Technical communication doesn’t deal with clichés as often as fiction does (or marketing, which, let’s face it, is just its own genre of fiction). But the other day I read the phrase “dead as a doornail,” and I thought I’d spend a couple of minutes on the subject.

By the way, if you’ve never heard the expression “dead as a doornail,” then I give you permission to insert any other cliché in its place. I will hold no grudge.

Sometimes we write clichés without even noticing that we’re doing it. It’s hard to avoid. And sometimes we write them ironically, or humorously. But sometimes, I think that people just don’t know how to avoid them, or they even think that clichés are a general good because they’re instantly recognizable. Everyone knows what “dead as a doornail” means, right?

Well, yes, everyone knows what dead as a doornail means, but that doesn’t make it good writing. Everyone would know what “dead as a plate of spaghetti” means, too, but they might enjoy the visual a little more.

Giving more than the facts

Which I think may be the point. Clichés don’t give the reader anything to think about. No one thinks about a doornail when hearing that phrase. I don’t even know what a doornail is. The audience gets the point, but nothing extra.

When someone says “I avoid it like the plague,” I don’t think about the plague. I just know that there’s some avoiding going on. But if someone said, “I avoid it like ears avoid Mike Tyson,” then I get more than just the main point (avoiding). I get a little morsel of extra meaning. You might not think it’s funny, but at least it’s memorable. At least I’m CREATING.

For every cliche, I can substitute something better. As you can see from my “avoid” attempt, it doesn’t take genius. Almost anything is better than a cliché, and almost anyone can do it.

“He was as red as a lollipop” is better than “he was as red as a lobster,” even though many lollipops aren’t red. The writer doesn’t have to work hard to think up lollipops as a substitute. It doesn’t take Dickens, but the end result gets you a little closer to Dickens. And Dickens was the cat’s meow fabulous wrapped in chocolate.

From A Christmas Carol, by Charles Dickens:

Old Marley was as dead as a doornail.

Mind! I don’t mean to say that, of my own knowledge, what there is particularly dead about a doornail. I might have been inclined, myself, to regard a coffin-nail as the deadest piece of ironmongery in the trade. But the wisdom of our ancestors is in the simile; and my unhallowed hands shall not disturb it, or the Country’s done for. You will therefore permit me to repeat, emphatically, that Marley was as dead as a doornail.

I recently spoke about technical communication to a group of students at the University of Melbourne. One of the students asked about books or other resources, which sparked an interesting conversation about how much new stuff there is to learn. After you’ve got the basics, and you learn the tools, how much more is there?

Well, I think there’s a lot. This week, I played around with a method of communication that I’d never authored before: comics.

For a few years, I’ve noticed comics pop up in a lot of places that I wouldn’t have expected. For example, I own the 911 Report, the Book of Genesis, and a biography of Richard Feynman, all in comic form.

But I never thought about it for my own work until it came up in an email thread about generational differences in communication. Some people recommended delving into comics for tech comm… and I did.

Skeptical Comic is skeptical

Yes, Skeptical Comic, anything that can help get an idea across can help with tech comm.

When you write a paragraph explaining a feature, the reader has to look at that paragraph and decide whether to read it. Even if it’s simple, reading a paragraph takes more effort than looking at a picture. When there’s a picture as well as words, then you can write and read a lot less.

Of course, I wouldn’t say that comics should replace steps 1, 2, and 3. When people want to accomplish a technical goal, they may not want to read a comic. But when the goal is simply to learn about a feature or idea, then a comic might be a good way to introduce the subject.

The Example…

I’ve pasted in a sketch that I put together in about an hour and a half of thinking and drawing. Here’s the setup:

We’ve built a feature that lets people “go back in time” to see what happened with their cable network design. The reader already has the document and knows the name of the feature, but may not have an idea of what problem it can solve.

This comic is designed to introduce the idea as a teaser and whet the reader’s appetite.

Note how simple I’ve made everything. I don’t really know how to draw, and I’m no expert on Illustrator or Sketchbook Pro, or anything like that. So I went with the minimum, and I hope it works.

Pretty simple. Maybe too simple? I’m new to this and I’m not sure. What do you think? Can comics make a difference in the way that we help our audience learn? Let me know!

Note: The book I’ve been reading is See What I Mean, by Kevin Cheng.

HOBGOBLINS (of little minds?)

Consistency is fundamental to tech comm, right? Don’t call it a dongle in one sentence and a dingle in another. But last week I found myself asking the entire dev team to be inconsistent. And, well, I’m 93% sure that I was right.

The issue wasn’t about terms (dongle/dingle), but about a missing period at the end of a customer-facing sentence in the UI. An example:

Press the SPACE BAR to destroy Alderaan

Where’s the period? When I mentioned that it was missing, I received a very reasonable reply from Development: Many of the older messages do not have periods. So we wanted to be consistent.

Consistency is good. Slavery is bad.

Honestly, I felt very happy that the dev team was even thinking about consistency at all. And they have a point. If we have periods on some error messages and not on others, then we look sloppy.

And most companies don’t have the resources (or the inclination) to go back and add a period to every error message that exists. It’s just too much work for a fairly small gain.

But. Staying consistent to an incorrect standard is not the way to go. Consistency is not our master, it’s our tool. In this case, that tool wasn’t the best one in the box.

Here’s my take:

If the style guide says that sentences should have periods, then we start writing our sentences with periods for NEW material, and we hope that the old material will catch up. I’m hoping that when people update old messages, they’ll add periods.

For a while, we’ll be inconsistent, which bugs me, for sure. But I think it bugs me less than it would to tell writers and developers to do something that’s wrong (according to our style guide) merely to serve consistency.

So, am I right? Am I violating the principles of tech comm, or upholding them?

Image: Francisco Goya [Public domain], via Wikimedia Commons

Have you ever wondered how to say something well without breaking a rule of grammar?

People occasionally ask me about certain rules of grammar. Of course, I do my best to oblige, but the very word “rule” starts us on an unhelpful path.

The only rule that matters is the one that says, “writing should serve the reader.” It’s the experience of reading that a writer should be concerned about, not the laws of writing. For every writing or grammatical rule that you give me, I can give you successful and respected writers who have ignored it.

Or, rather, they haven’t ignored it. They’ve understood it and chosen the right time to go a different way. And that’s really the point.

Grammatical rules aren’t rules

Grammatical rules aren’t chains. They’re not law. They’re not even rules, really. Instead, they’re very good advice from the ages.

Whatever the rule is, you can break it and still be a good writer. But you should break it mindfully. That is, you should know that you’re doing it and have a good reason. The rules are there because they’re usually the best way to accomodate your readers’ need for clarity and precision. But if you know that, and you know that breaking the rule will be better for the reader, then go for it!

An example: Most style guides say that the period goes inside the quotation marks, “like this.” At the very least, I think most people would say that you should be consistent with your punctuation.

But as many tech writers know, it’s common to put the period outside the quotation marks when it’s important to be clear about what’s being quoted. After all, I don’t want the reader to put a period at the end when I say, “visit my website at www.savethesemicolon.com.”

Dangle a modifier if it will help your audience. Sentence fragment? Works for me. But do it mindfully. Remember your audience and its needs. The rules are only guidelines, but they’re often very good guidelines.

All this goes for literally every rule of grammer and writing that exists. Some rules, you’ll find yourself following all the time (“Me go store buy milk” wouldn’t make it past most editors), but it doesn’t mean that they’re inviolable.

Am I right about this? Am I missing something important? Let me know!

If the text is small and simple (like a change to the copyright year, for example), then you could do worse than using Acrobat Pro’s built-in redact feature.

The redact feature is intended to find and delete text from a document. But the feature allows you to add new text to the place you just deleted text from. Hey, that sounds like find and replace to me.

This trick is really best when the text is standing alone, like in a header or footer, rather than in the middle of a paragraph. Watch this 5 minute video and let me know if it’s helpful. And I apologize in advance for how small/blurry the video is!