I’ve always known that Weird Al was somehow spying on my life. I now have proof.

Posted in Fun | Leave a comment

Passing the Buck

Years ago (in the mid-1990′s I think), I was doing a contract for a client that developed their own touch-screen technology for the food service industry. I had submitted a draft of the documentation for review to a client with a one-week turn-around. A week later, I sat in the client’s meeting with the heads of various departments and prepared to receive their comments.

Project Lead: I didn’t have time to review it, so I gave it to the head of Marketing.

Marketing Lead: Reviewing the Guide wasn’t really our job, so we gave it to the head of QA.

QA Lead: We didn’t have time to review it, so we gave it to the programmer.

Programmer: I’m too busy with coding to be reading the Guide, so I gave it to the Project Leader.

Embarrassed, the Project Leader turned to me and said “We’re very sorry for wasting your time. Charge us for the whole day and give us another week.”

One week later, I returned to their meeting room and all the same people were there, except they looked really angry. Apprehensively, I awaited their feedback.

Project Lead: I’ve been hearing horrible things about this Guide, so I’m going to let Marketing have their first crack at listing the problems.

Marketing: Reviewing the Guide is *still* not our job, so I don’t know why you even asked us again! We gave it to QA because finding bugs is their job!

QA Lead: Our job is to test the application, not find typos! We’re already overloaded without having to read the Guide! We gave it to the programmer. He’s the one who should know if the Guide is correct or not!

Programmer: This Guide is useless and a piece of crap!

Project Lead: So you did review it this time?

Programmer: Well… no. But I showed it to my mother and she *hated* it.

Horrified, the Project Lead said “I’m very, very sorry to waste your time again. Charge us for the day and I’ll have comments for you by the end of the week, you have my word.” As I walked out, the programmer was getting his head taken off by all the department heads. I finished up the project that month and they were quite satisfied with the work.

A couple of months later, I was paying for my meal at a restaurant when I noticed the cashier was having trouble punching it in. I gave her some advice on how to punch in the order, and when it worked, she looked at me incredulously and asked “How did you know that?”

I reach to the side of the cash register and pulled out the client-printed User Guide and stated “Because I wrote this!”

Posted in Fun, Writing | Leave a comment

Amusing Typo

While reviewing a technical document, I found a most humorous typo: suedo-code. Unless the code is actually made of suede, I’m going to assume the author meant Pseudocode.

I posted about this typo on my Facebook page and hilarity ensued:

Susan P: Maybe it’s sudo-code: code with someone else’s privileges.
JD: Or Sudoku-code: writing code in a 9×9 grid.
Susan P: Swedo-code: BORK GET BORK.
JD: How about Swayze Code : ghost – writing dirty code in a roadhouse style.
Susan P: Do-Si-Do Code: Code called out then performed through dance.
JD: Sous-Chef Code: Writing code while your boss watches over your shoulder. The. Whole. Time.
Rob St-M: Sue-sue-suedo-code.
Sarah G: Sudo-code: code you need to wrestle with.
Shahna S: Suet-code: the woodpeckers love it.
JD: Suez-code: this bit of legacy code allows a free flow of information between two databanks. Conflicts arise when rival coding teams try to lay ownership claim to the Suez-code and historical hilarity ensues.
Susan P: Churro-code: It only seems crunchy, but once you’re past the somewhat spicy bits there’s nothing but sticky goo beneath. Mind you, this is a design feature.
Sari S: A Boy Named Sue-code: only makes sense when played on a guitar.
Ron D: Sue-de-code: ’cause dey done robbed mah bits
Douglas T: Suedocode? No, Coderouy!

Posted in Fun | Leave a comment

Random Advice

Just in case any of you go crazy and decide to be Technical Writers, let me impart this nugget of wisdom: when writing instructions, be aware that users PRESS keys on a keyboard and they CLICK buttons on the interface. These terms are NOT interchangeable.

Also, the SCREEN is the piece of hardware you use to see the application, but the application itself appears in a WINDOW. These terms are also NOT interchangeable.

Does no one remember what happens when you cross the streams? Bad things happen. BAD. BAD. THINGS.

Posted in Advice | Tagged | Leave a comment

Pictures vs Words

I submitted a sample draft of a User Guide to my client a few days ago and I got the feedback today. Most of it was fine, but this one comment made my left eye twitch:

Is there a way to reduce text and replace it by illustration like ikea user guide? I think it would be much efficient.

I don’t think using Ikea as the model is a good idea. Ikea has a reputation for having completely illegible and confusing picture-based instructions.

They say that a picture is worth 1000 words, and in certain cases, that’s very true. For example, this is true for art when each person can have their own interpretation of a piece of art and come up with their own 1000 words to describe it and have it be perfectly valid (if not, it’s at least open for debate).

But when it comes to technical instructions, each reader must come up with the same, precise 1000 words to successfully complete a task. This is the beauty of words because they are precise and specific, unlike a picture which is always open to the randomness of interpretation.

Words:  good. Words and Pictures: better. Pictures alone: risky. A friend pointed me to this great illustration at Retronaut:

Posted in Advice | Tagged , | Leave a comment

Creating Topics in Robohelp from a Frame document

I’m currently relearning the joys of RoboHelp after a few years and a few versions of unfamiliarity and I hit a snag on trying to convert documents into topics. I’m using Framemaker 10 and RoboHelp 9 (as part of the Adobe Technical Communication Suite 3.5).

I had written the Online Help topics in Frame 10 using Headings 1 to 4 to provide some structure. Once the content got through the First Draft of approval feedback, I wanted to convert that Frame document to Robohelp.

What I wanted the conversion to do is to create individual topic files based on the heading level instead of each document being one big topic file with multiple heading sections. But when I tried to convert the Frame document to Robohelp, it created one big topic per Frame file.

After padding through the Adobe support forums a bit, I found the answer.

  • RoboHelp 9: When importing a Frame document into RoboHelp (File > Import > FrameMaker document), you click Next on the first dialog box, then click Edit.
  • RoboHelp 11: Select the Project tab, look to the Link panel, and click Settings. In the Import tab, click Edit conversion settings (for Frame or Word).

Open the Paragraph tree, select each applicable Heading level style, and click the Pagination checkbox. This will create a topic every time it encounters the style you specify (in my case, Headings 1 to 4).

If you have a cover page per chapter, you may want to select the Paragraph styles on that cover page and select Exclude from output. I often find that the cover pages in a book have no relevancy in Online Help.

Posted in Advice, Technology | Tagged , | 2 Comments

They’re singing my song

Whenever I get to sing Paperback Writer on Beatles Rock Band, I always filk the lyrics and sing Technical Writer instead. Now a friend found the full version of my tribute song on YouTube. Although the author is not a technical writer himself, he is apparently involved with one who must talk about her frustrations over the dinner table

It’s not credited in the video, but I’m assuming this is performed by the Pete Zolli Trio.

Posted in Writing | Tagged | Leave a comment

Blueberry Perception of Techwriters

Last week, my 7 year-old Toshibasaurus finally broke down (actually, it was the battery and power pack that died). I could just replace the battery/power pack, but truth be told, the Toshibasaurus was getting long in the tooth and slow in the CPU, which meant that it wouldn’t be able to run the applications that I’m contracted to write about. This means it’s time to go shopping!

So I hit up the usual places just for specs and general pricing like Future Shop and Best Buy. I don’t usually get my higher-end hardware in these places, having been burned in the past, but sometimes they have really good deals if you know EXACTLY what you’re looking for. There’s something about buying a computer in the same store that you can buy paperclips that makes me twitchy.

I found a Toshiba in Best Buy that had decent specs for what I needed, but when I checked the System settings in the Control Panel, the laptop in the showroom had seemingly different specs than what was being advertised.

Plucking up my courage, I approached a Best Buy Blueberry (that’s what I call the guys who work there) and asked him about it. He assured me that it’s normal that the specs say that the drive is 640 Gigs, but that the actual usable space is 580 Gigs. Why that was, the Blueberry wasn’t sure, but he somehow seemed to know that this is how it’s always been since the dawn of laptop typewriters. He said that this is how Toshiba does the math in terms of storage space and rounds it down (by 60 Gigs!). It sounded fishy to me, but after checking it out online, it turns out that it’s normal for the available disk space to be lower, but that’s because of the way the drive is partitioned: the tech geeks split the drive into sections reserved 60-80 Gigs for emergencies.

Then I pointed out to the Blueberry that there were only two USB slots when the advertising says there are three. After checking out the laptop, he assured me it was a typo. As it turns out, the eSata slot is a combo slot that accepts USB drives, but the Blueberry didn’t know that. Frustrated, I tried to suggest that since the tag was wrong about the drive space and the number of USB ports, that the price must be off by $100 (I too understood the concept of rounding down). The Blueberry looked at me dumbfounded and replied “I dunno what you mean.”

He then tried to sell me another laptop by asking me what I needed it for. I told him I was a technical writer and got a blank look from him. “Y’know… I write the software guides that come with the applications, so I need a laptop powerful enough to run the latest, cutting-edge software.”

The Blueberry was confused. “What do you mean? What applications?”

“The latest applications that are being developed right now, as we speak! I’ve written books about database management apps, military simulators, 2D animation tools, 3D graphic tools, music database management systems! I need a powerful laptop to be able to run those applications and be able to run the software I need to write about how they work.”

At this point, the Blueberry had pegged me for the hippy, fringe, outcast that I was. He waved my explanation away saying “Yes, sir. I know what blogging is. You can use this laptop to write your little articles, burn DVDs, and listen to music all at the same time.”

Instinctively, I reached for my sword to cleave this Blueberry in two perfectly-proportioned halves to answer this insult, but I forgotten it at home. Instead, I bid him a curt “Good day” and brewed a satisfyingly dark, stormy cloud over my head, and stomped out of the store.

I’m following other avenues to finding my new laptop, and in the meantime, I’m plotting my revenge on the Blueberry by either hauling in my portfolio of User Guides and forcing him to look at them all, or I may try to organize my own Blueberry invasion of the store.

Posted in Advice, My Gadgets | Tagged | Leave a comment

Games on the ExoPC

I won’t lie… I love playing video games. I’m more of a PC gamer than a console gamer (although I do own a Wii), but I wondered if how tablet games would stand up to PC games that have a keyboard and mouse.

The ExoPC has a few of its own games like Air Hockey and the Line Rider, and it certainly works well with the classic Windows games (Solitaire, Hearts, Spider, etc.).

Over the Christmas holidays, I installed Steam and Plants vs Zombies. This game is even more fun on a tablet! Being able to tap and plant your garden against the hordes of oncoming zombies is very satisfying (although the conveyor belt levels seem to require a double-tap to make the selections).

Today I learned that the latest gaming craze Angry Birds, which was until recently only available on Apple product, is now available in a Win32 version, which means it can be played on the ExoPC.

You can read about it here. It costs $9.99 (there is a special right now where it’s being sold for $4.99). You can also see a video of it running on the ExoPC on YouTube thanks to DarkKevin!

As for other games I like (like WoW and Team Fortress 2), I can’t see them working very well on an ExoPC without a keyboard and mouse, although with a docking station, they may still be possible, I guess. I think the ExoPC’s hardware can only handle less processor/graphic-intensive games. Time will tell.

Posted in My Gadgets | Tagged , | Leave a comment

Navigating DOS menus

I keep discovering that the ExoPC is better designed than I previously believed.

Because it’s a Windows OS, it sometimes doesn’t shut-down properly and when you boot it up again, you get a text-based DOS menu asking you to take action. But because it’s a tablet, there’s no keyboard or mouse and the touch-screen interface doesn’t work, so it is seemingly impossible to interact with a DOS-based menu system. The few times this has come up, I was at a loss to know what to do, so I just let the timer runout and make its own selection.

Yesterday, I got a boot message where I was forced to make a choice (there was no timeout), so I was stuck. After rebooting several times and getting the same message, I was about to hit the ExoPC forums to hunt for an answer when I made my discovery.

In the top left corner of the ExoPC, there is a small mysterious  orange circle. By sliding your thumb over this circle, you can move up or down a list of options in DOS, just like pressing the Up or Down arrows on a keyboard. Tapping the orange circle is like pressing the Enter key.

Now when faced with a DOS menu that has no mouse interface, I can scroll through my options by sliding my thumb over the orange circle and tapping it to make my choice. Awesome! Kudos to the ExoPC team for coming up with such an elegant solution to this thorny problem.

And although it’s a bit late, Merry Christmas, Happy Yule, and Happy New Year to all!

Posted in Advice, My Gadgets, Technology | Tagged , | Leave a comment