STS Blog

The I’d Rather Be Writing techcom blog posts 10 Alternative Tests for Technical Writing Job Candidates. Not all of the ideas apply to our situation at STS, as we are all technical writers here, we don’t really have in-house documentation, and tend to recruit more entry-level folks who we can mold to our ways before they are corrupted by outside influences. However, there were some interesting suggestions.

I like number 10, especially:

Check to see whether the writer formatted his or her resume with styles.

I look at the formatting of resumes, cover letters, and writing samples in detail before I read them. Seriously, folks. Your resume is a great opportunity to show that you have some grasp of good information mapping practices as well as some skill in Microsoft Word. (And as awful as Word is, most technical writers will be using it an awful lot.)

Using styles gives you bonus points in my book. But if you don’t use styles, you should at least make sure the formatting is consistent. If some of your job titles are 10 pt. and some are 11 pt., I will notice. If you have two hard returns between some items and one between others, I will notice. If you use strings of spaces instead of tabs or paragraph styles to position your text, it will never line up perfectly, and I will notice.

Lack of attention to detail is a deal breaker in a candidate, and a poorly formatted resume is a great big warning sign about your ability to spot those tedious errors that a quality technical writer must be able to spot.

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:

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:

Apparently Adobe has gotten serious about changing their mind about giving up on the technical documentation market. After reviving RoboHelp in response to MadCap’s success with Flare, they’ve just now come out with a new version of FrameMaker, the first release since FrameMaker for the Abacus in 208 B.C.

Among the exciting new features in FrameMaker 8: Support for Flash. Which is great, because I’ve been looking for a way to get animated banner ads into user manuals for years.

Tell Someone About This Post:

Studies have shown that people can remember between five and nine items at a time depending on the information. By using a range of adding two or subtracting two, we get the number seven.

In general, people can only remember seven things at one time. When writing instructions and steps, we should keep the number seven in mind. Try to keep instructions to seven steps or less. If a set of instructions is long, try breaking it down into groups instead of one long list of steps.

It is also good to keep sentences 21 words or less. If a sentence looks complex, it probably is. Do not force the reader to read a sentence more than once to understand its meaning. Studies show that people retain information from sentences no more than 21 words. Can anyone guess what 21 is divisible by?

Here are links to more information about the studies and memory:

http://www.nwlink.com/~donclark/hrd/learning/memory.html

http://www.sheridanc.on.ca/~sherman/rap.dir/weeks1to4/Cutfog.html

Tell Someone About This Post: