Weekly links roundup

A thousand words, or a waste of space?

A picture is worth a thousand words. I wish that I had $20 for every time I’ve heard that hackneyed phrase. Or even $10. I probably wouldn’t be rich, but I’m sure that I could pay off a chunk of my mortgage …

Seriously, though, there seem to be a number of technical communicators who take that phrase seriously. They create documentation that’s packed with screen captures, diagrams, flowcharts, and more. In most cases, the images don’t do much for the document except take up space.

Images included in documentation need to be more than just mere eye candy. The should illustrate something that’s difficult to describe using only words. Images enhance the text; they don’t replace it. To be honest, most images that I’ve seen in many of the user guides that I’ve read have done nothing to enhance the text I was reading. They just mirrored what I was looking at. Digital repetition at its finest.

I’ve heard some technical communicators argue that including screen captures is important because they “let the user see what’s happening in the application.” Yes, I’ve heard that sentiment more than twice. What we fail to realize is that someone will be probably be using the documentation while in front of an application or gadget. Unless they’re trying to familiarize themselves with a product, they won’t read the docs while riding the bus home or just after dinner.

That said, images aren’t always unwelcome. As I mentioned a couple of paragraphs ago, a well-chosen image is useful. But the key words here are well chosen. Just capturing every screen you can and sandwiching it between blocks of text just doesn’t work. Like anything else in your document, images should have a purpose. If they don’t strip them out.

How do you use images and screen captures in a document? Feel free to leave a comment.

One year on the job

Susan Wu (who blogs at Shanghai Tech Writer) has just finished her first year as a technical writer at National Instruments in (surprise, surprise!) Shanghai. She writes a retrospective of that year here. From the looks of it, that year was packed with a lot of learning — not just learning related to mere technical writing, either. What’s evident from this post (and I’m not just talking about the last paragraph, either) is that Susan enjoys what she’s doing.

It’s been … well, quite a few years since my first one on the job. Looking back, I (vaguely) remember some of that early joy along with a few frustrations that helped me grow professionally.

So, here’s a question I’m throwing out to the fives of people who read this blog. What do you remember (good and bad) about your first year as a technical communicator? Leave a comment, and the best ones will be collected into a post sometime in the near couple of weeks.

Jargon, jargon everywhere

And sometimes it’s an excuse for us not to think. At least, not to think about how to properly describe something to folks who might not be as familiar with a technology or an area as we might be.

A friend of mine keeps reminding me (and anyone else who will listen) that every group has its own jargon, acronyms, buzzwords, and terminology. In many ways, knowledge of that language seems to convey upon the people in that group some sort of elite status. I don’t think that’s true, but a lot of people do.

Technology is no different. I always say that the world of technology is third behind the UN and the military in acronyms, but it rivals the military in jargon. And, to be honest, hearing a lot of the jargon that’s bandied about in tech circles hurts my ears and my brain. That said, we’re all guilty of using jargon — I know I am sometimes.

New York Times columnist David Pogue has put together a list of tech terms to avoid. He includes some of my (least) favourite terms including the dreaded functionality.

Are there any terms or bits of jargon that you despise? If so, why not share them by leaving a comment.

More cool stuff from Cool Stuff

Sun’s Cool Stuff blog has yet another interesting post, which points to summary of a course on how to customize the DITA OpenToolkit. According to the post:

This paper outlines the most important processes, but it leaves out many of the details, tips, and debugging notes that were included in the course.

From outline, it looks like the customization process is a bit time consuming. But, then again, you only have to do it once. Or, at least, once in a while. I mean, how often do you make major changes to your FrameMaker or WebWorks templates and projects?

Admittedly, I’ve only toyed with DITA; I don’t know many of the little details. But the information in the course summary on template extensions looks interesting. I’m wondering if it’s as (relatively) easy as creating a customization layer in DocBook.

Lessons in interface design from Apple

The other day, I came across the Apple Human Interface Guidelines, which is a document that helps guide developers to create consistent, easy to use applications that will run on Apple’s devices.

The guidelines are very detailed. Check the link above to see for yourself, or download the 28+ MB PDF version. While skimming the document, I ran into two interesting sections.

The first is titled “Involving Users in the Design Process, which states:

The best way to make sure your product meets the needs of your target audience is to expose your designs to the scrutiny of your users. Doing this during every phase of the design process can help reveal which features of your product work well and which need improvement.

When you give people an opportunity to use your product (or a prototype of it) you may uncover usability problems that you did not anticipate during your initial design phase. Finding and eliminating these problems early can save you time and money later on. Clearly identifying the needs of your users helps you create products that deliver effective solutions and are typically easier for them to learn and use. These improvements can translate into competitive advantages, increased sales, and enhanced customer satisfaction.

The second is titled “Keep Your Users in Mind“, and starts off with the following words:

In addition to the basic principles of interface design, consider the needs of your audience. Are your users more comfortable in a language other than English? Do they have special needs that might affect the way you present data to them? The following sections identify areas that might influence your design.

Admittedly, I don’t own a Mac. And I’m definitely not an Apple fanboy. That said, I’ve used and played with them sporadically over the years, though. Something that always struck me was the general consistency of the applications, and the (relative) ease of use of Mac OS. Obviously, there’s something to be learned from reading the Apple Human Interface Guidelines.