STS Blog

Someone recently posted an interesting question and answer over at TechWR-L that I wanted to touch on briefly as it is a topic on my (obviously) neglected list of things to blog about. The question was about how much jargon is okay to use in documentation. The answer posted in a comment was:

You only have too much jargon if the jargon interferes with the ability of the audience to understand what you’re trying to communicate. If the audience speaks that jargon on a daily basis, you’re doing them a disservice by trying to eliminate their jargon.

The word jargon comes loaded with a lot of negative connotations. Think corporate jargon: “leveraging synergistic best practices going forward.” And obviously, that sort of nonsense just attempts to obfuscate the fact that the person using the phrase has no idea what they’re talking about.

But when you’re talking about industry-specific terminology, jargon plays an important role. It increases the efficiency of communication between members of the community by cramming a whole lot of meaning into a small linguistic space. You can say SOA to software developers and activate a whole slew of concepts in their mind with three letters. It would take paragraphs or pages to give a layperson even the highest-level understanding of the same.

And isn’t efficiency of communication a best practice that technical communicators should be leveraging?

Ultimately, the issue boils down to one of knowing your audience. Can you be sure that your audience is familiar with the terminology? It can be a difficult issue, especially when you’re writing about a topic with which you don’t have a lot of familiarity. Remember that just because you don’t know what industry terms mean does not mean your audience doesn’t.

This is something that technical writers have to work with their subject matter experts (SME) to determine. “Does the audience know what this term mean,” is a good question. I’ve found that often SMEs haven’t given the question a lot of thought, and asking them provides a good starting point for a discussion about what the audience knows.

One point to keep in mind here is that your primary audience isn’t always your only audience.

That said, if you can be sure your audience is familiar with the terminology, you won’t be doing them any favors by cutting out jargon for the sake of cutting out jargon.

Tell Someone About This Post:

After years of slander and ridicule, passive voice has been found to be useful by Jakob Nielsen’s eye-tracker research. Mr. Nielsen’s article, titled Passive Voice Redeemed for Web Headings, makes an excellent case for the use of passive voice as a sneaky way of “front-loading” keywords in headings for blog posts, articles, or other web content. It cites recent eye-tracker research as proof that Internet users tend to focus only on the first few words of a headline.

Although this goes directly against what most of us have been taught for years (passive voice is punishable by forced attendance to a networking event flogging at Shoap Technical Services), Nielsen makes an excellent point. While using passive voice is generally not a good idea, there are circumstances where it actually makes sense, particularly if it makes your writing more effective.

Of course, it’s not hard to see how grabbing the reader’s attention makes for an effective headline. Since readers are more likely to click on something interesting, and more hits = good, passive voice is probably a risk worth taking when it comes to writing headlines.

Link (via Boing Boing)

Tell Someone About This Post:

Why is it that when people get stuck trying to figure out a piece of technology, they invariably pick up the phone and call a help desk rather than open a manual or, if it’s available, click on the help button?  Certainly, it would be quicker to find the answer than wait for the “next representative to become available.”  The answer, of course, is obvious, as anyone who has tried to read a technical manual can tell you: Either the answer isn’t readily available (can’t find it) or doesn’t make sense (can’t figure out what’s being said when they do find it).

As a technical writer, educator, and owner of a technical writing consulting business, I am acutely aware of this situation.  Unfortunately, most of what passes for technical writing is bad.  Anyone who has tried to assemble anything that comes in a box knows how difficult it is to turn the assortment of wood, screws and bolts into a bookcase by simply following the pictures in a manual.  Or the unfortunate computer user who receives a message that the program has encountered a problem and must shutdown and looks hopelessly at the 700 page manual that came with the computer and picks up the phone.

So why is this?  The problem, as I have observed, is most often due to the fact that the people writing about technology don’t understand it themselves.  And, as I used to preach when I taught Composition 101 at varoius colleges and universities, if you don’t understand what you’re writing about, no one will understand what you’ve written.  This is true whether you’re writing about what you did last summer or how to use API or how to repair a jet engine. 

Unfortunately, the number of people who can understand technology and have the skills to describe it is faily small.  Most of the candidates who interview at our company are competent writers but don’t have a clue how things work.  When I question them about their apparent lack of understanding, they tell me that we just have tell them what to write.  Yikes!

The situation is not as hopeless as it sounds.  We’ve discovered a number of candidates who are very technical — and not only can write but enjoy writing — but don’t want to be engineers.  Usually, we find that they are better understanding the technical aspects of the project than they are at the exposition, but we can work with that: We can edit the material and work with them to make the manual clearer and more effective.  The opposite is rarely true: No matter how well the person can write, if he or she doesn’t understand the technology, no amount of work (short of rewriting the manual myself) is going to make material any better.

Tell Someone About This Post:

It’s link round-up time once again! Here’s what I found on the Interweb this week:

• Internet Resources for Writers - Fairly self-explanatory.  Can’t think of anything I’d add other than “Lorem Ipsum” text to quickly copy to create placeholders…
• Fotoflexer (via LifeHacker) - If, like me, you are a technical writer who spends most of the day switching between several computer systems… well, that’s just it, you use several computer systems.  And sometimes its just not possible to have Photoshop installed on every single machine.  Fortunately, you can use Fotoflexer to edit pictures inside of a web browser.  Problem solved!
•  15 iGoogle Widgets for Web Workers - Finally, if you EVER use Google for anything, chances are you’ve personalized your iGoogle page (or at least you’ve seen it before).  Here’s a list of 15 handy thingees that will make your life a bit easier.  I like the procrastinator’s clock (for I am a procrastinator) and the timesheet tool (because like most contractors, I write up and send out a timesheet every single day…)

That’s all for now.  TGIF!

Tell Someone About This Post:

I recently learned about the FAT32 file size limit and thought I’d share.

One of our clients recently purchased a Western Digital External Hard Drive to use as backup storage and a way to pass large files around quickly and efficiently.  Unfortunately, we received write errors on the drive when we tried to copy several items onto it.  The reason we were getting these errors was because the hard drive was formatted as a FAT32 file system.  This was nice, because FAT32 is a pretty simple file system that both Windows, Macs, and other Unix Operating Systems can read.  However, you cannot copy a file larger than 4 GiB minus 1 Byte (2³²?1 bytes) into a FAT32 file system.  Having multiple raw video files on the machine, well over 4 gigs each, this posed a problem.

 My solution was to partition the hard drive into one 32 GiB FAT32 file system and the rest of the drive into NTFS.  This allows me to put files of any size onto the NTFS partition and still maintain some of the flexibility of the FAT32 partition on other OS’s.  You could also create a Mac partition with a Mac file system, should you desire.

 Hope this helps answer someone’s question.

Tell Someone About This Post:

The second in a series of posts where I pretend to be a programmer.

FrameMaker really shines when you have a suite of large documents that all have to have matching formatting. You create one set of paragraph styles, one set of master pages, one set of reference pages, etc., then you import all the properties from your template into each document, and — Voila! — consistency across all.

In the ideal world, your set of formats never needs to be edited and never varies across your whole suite of documents. Of course, we don’t work in an ideal world, all sorts of things can conspire to ruin your perfect template, and one day you look at your paragraph catalog and you have a hundred styles when you only needed twenty. Maybe some of them came from those times you had to import documents from Word. Maybe others from that time the temp worked on your docs while you were on vacation. Maybe your boss asked for a new style for ideas that aren’t quite Notes but aren’t quite Warnings either.

But now, the only way to get rid of the extra styles is one-by-one using Delete Formats from Catalog. How tedious! And you have to do it for each of your documents, since the import function isn’t destructive.

If only there was a better way …

Read the rest of this entry »

Tell Someone About This Post:

I’ve been using and enjoying MadCap Flare for a number of webhelp projects lately. I find that it’s superior to RoboHelp in pretty much every way (except for stability and bug count.)

One particularly annoying bug that I’ve found is that Flare, on occasion, decides to insert non-breaking space characters instead of regular space characters when you hit the space bar. The result is that you end up with line breaks in weird and unsightly places when you generate webhelp or printed documentation.

In most cases, the easiest way to fix the problem is to replace all instances of the entity with a regular space character using your favorite search and destroy program. But what happens if you used some of those characters on purpose? I had this problem recently when documenting some XML formats, using non-breaking spaces to indent the lines of sample code.

Since I couldn’t just search and destroy on without losing all of my hard Ctrl-space work, I wrote a script in Ruby to eliminate most non-breaking spaces while preserving the ones I wanted to keep. Read on for more details.
Read the rest of this entry »

Tell Someone About This Post:

As I learn more about Office 2007, I’ll have plenty of specific tips for you. Until then, I want to provide the best advice ever given to me: Don’t be scared.

Our familiar Word toolbars have been replaced by this:

At first glance it is chaotic and cluttered. Nothing is where it should be. We have no idea what to click. Worse yet, we have no idea what to expect when we actually click something. At times like this, when we are surrounded by the unfamiliar, it is important to remain calm.

If we immediately rush ahead and try to make Word do our bidding, we’re just going to frustrate ourselves. However, if we take a deep breath and examine our surroundings, familiar icons will begin to stand out.

The first thing I’m going to do is mouse over a button I recognize…

…and be pleasantly surprised. Now, not all of the tips you’ll find are as thorough as this one, but many of them are.

Don’t bother typing anything at first. Just take some time and explore the interface. As with all things in life, the more you interact with something, the more familiar it becomes.

1i

P.S., Be sure to note that UFO in the top left is actually a button!

Tell Someone About This Post:

When I broke into this business in the early 80s, my first gig was as a technical writer for a large electronics manufacturer. I had been placed there by a broker (who received a percentage of every dollar I billed). Thus, when I told my manager at the electronics manufactuer that I had nothing to do and that he was wasting his money (development on the project hadn’t started yet), the broker was not terribly happy with me. In fact, he threatened not to pay me for the time I had been there.

From this unpleasant situation I realized that there was an accountablity issue. I felt accountable to the person I was working for — the electronics manufacurer — not the broker who hadn’t a clue what I was doing so long as I continued to bill. And it was at that moment that I decided that when I had my own company, my writers would be full time employees of my company, be accountable to me, and I would be accountable to my clients.

Over the years, this model has worked well. While scheduling can sometimes be a nightmare — making sure everyone has billable time all the time — at least I know and can assure my clients that if there’s nothing for us to at a particular time, we don’t need to be there and come back when there is something to do. This has worked well for my clients (for obvious reasons), for my writers (they feel like they’re always productive) and for me. Mostly, though, it’s just good business.

Tell Someone About This Post:

If ever there was a typo so vile and loathsome that it deserved its own domain, this is definitely it.

Tell Someone About This Post: