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. When importing a Frame document into RoboHelp (File > Import > FrameMaker document), you click Next on the first dialog box, then click Edit.

Open the Paragraph tree, select each 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).

Posted in Advice | Tagged , | 1 Comment

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

Explaining Menu commands

Way back in the days when dinosaurs and unicorns roamed the earth, not many people owned what we now recognize as a Home Computer. And even those people that did own a Home Computer, it was a command-line-based system that did not have buttons, menus, drop-down lists, and the myriad of other interface tools that we take for granted today.

But now if you hop into the WABAC machine with Mister Peabody and Sherman, we’ll leap forward 30 years to the present day. The dinosaurs and unicorns are still here, but they’re wired to the teeth (and horns) with portable computers and cellphones that have more computing power than the systems that put Mr. Armstrong on the moon.

The point of all this dizzying time travel is that the modern computer user understands the concepts of menus, mice, buttons, and listboxes. This means that we sidestep the explanation of how to use these interface tools, putting the focus on the product instead.

For example, the old way of explaining how to select a command from a menu might have looked like this (yes, including the graphics):

1. Open the View menu. The following commands appear:

2. Open the Explorer Bar submenu. The following commands appear:

3. From the Explorer menu, select Tip of the Day.

All this extra information is not needed by the modern reader, making the procedure heavy and overly-wordy. If you can safely assume that the reader knows how to open a menu, you can shorten the above procedure to single step:

1. From the View menu, select Explorer Bar > Tip of the Day.

or

1. Select View > Explorer Bar > Tip of the Day.

Using the brackets, you can drastically shorten a procedure, provide a clear path to the command(s), and accelerate learning. A shorter procedure is less intimidating to a novice user and less annoying to a technically-minded user, making the technical document easier to use and allows the reader to return to the tool quickly and efficiently.

Of course, you can take this philosophy too far and make your procedures so short that only an advanced user would understand them. This is why audience analysis is so critical to determining the level of information to include in the technical documentation. Find out what they know already, determine what they need to accomplish, and teach them how to use the tool.

In performing your audience analysis, talk to the people who know the audience, not the tool. Interview the trainers, the product designers, the sales people, and the support people. I would recommend that you do NOT speak to the programmers/engineers for this type of information. The programmers/engineers tend to know how the individual parts work, but they don’t understand how the tool works as a whole, and they don’t need to know how a user will work with it. There are exceptions to this generalization, but by and large, the programmers/engineers are too immersed in the tool itself to be objective enough to evaluate the level of explanation needed to a person who has never used it.

Posted in Advice, Writing | Tagged | Leave a comment

Reading e-books on the ExoPC

One of the reasons I went with the ExoPC Slate in the first place was the ability to read books on it. Sure, there are the Kindles and Kobos out there, but they aren’t nearly as sexy as the ExoPC Slate!

As it turns out, Kindle has a PC version of their reader that you can load into Windows 7 that is free! You can download it here from the Amazon Kindle website.

When you buy a Kindle, it comes with 1000 books preloaded on it. Downloading the Kindle Reader doesn’t provide you with 1000 books, but fortunately, there are many books available for your to download for free!

Amazon’s List of Free Books

Free Kindle Books (largely made possible by Project Gutenberg)

Project Gutenberg for Canadian literature

Project Gutenberg main site

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