Review: Page Layout and Design Tips from Jean-luc Doumont’s Trees, Maps, and Theorems

Given the engineering audience, one can’t hope for too much style and flair in the prose, but it reads like a college textbook, outlining basic principles in a flat way. It is too focused on “clarity, accuracy, correctness, etc.” (p.79) to make for a fun or engaging read.

Johnson, Tom H. I'd Rather Be Writing (2009). Articles>Reviews>Document Design>Visual Rhetoric

How Google Does Help

Last week Google released Google Voice, a service that allows you to integrate all your phones into one number and includes a host of features, including voice mail, recording, conference calling, and other services. To help users get started, Google Voice has a list of 20 short videos. Only the overview video contains animation. It’s certainly the video they’ve put the most work into, and it also functions as marketing collateral.

Johnson, Tom H. I'd Rather Be Writing (2009). Articles>Documentation>Multimedia>Case Studies

What Users Don’t Care About

Part of the problem in our attempt to demonstrate value is that our help deliverables look the same as they did 15 years ago, more or less. Online help and a PDF manual. It’s not a format that engages users. The web marches forward with innovation after innovation, while the technical communicators are figuratively hunched over keyboards, staring at CRT monitors, wearing 1950s horn-rimmed glasses, typing away.

Johnson, Tom H. I'd Rather Be Writing (2009). Articles>Documentation>User Centered Design

A Mile Wide and 30 Seconds Deep: A Metaphor for Help from Mike Hughes

Help needs to be a mile wide—it must cover everything—and 30 seconds deep—tackling only small amounts of detail at any given point.

Johnson, Tom H. I'd Rather Be Writing (2009). Articles>Documentation>Technical Writing

If You’re a Writer, Write

Why is it that, given the opportunity and tools to write, so few embrace it? I have several thoughts as to why.

Johnson, Tom H. I'd Rather Be Writing (2009). Articles>Writing>Publishing

Is This Meeting Really Necessary?

In a world of virtual tools—blogs, wikis, feeds, forums, listservs, e-mail, IM, chat, Twitter, social networks—one would think that the traditional sit-down, face-to-face meetings had been relegated to a place in a historical museum among other old, discarded traditions (like wearing cravats). But even in the 21st century, many people still believe that if you want to accomplish serious planning and discussion, you need an in-person meeting.

Johnson, Tom H. I'd Rather Be Writing (2009). Articles>Project Management>Collaboration

Three Questions to Start Thinking Like a Content Strategist

A content strategist looks at all the content from a holistic point of view, treating everything as content, and analyzing whether each aspect of the content aligns with the company’s messaging, branding, and intent. The content strategist is acutely aware of the multifaceted nature of the user experience. It’s not just the user interface that influences the user, or the marketing material, or the training — it’s all of this and more, working together as one. The whole user experience is the content strategist’s domain, not just help materials or written text.

Johnson, Tom H. I'd Rather Be Writing (2009). Articles>Content Management>Content Strategy>Project Management

How to Implement Single Sourcing: Interview with Neil Perlin

Neil Perlin, a renowned trainer, consulter, and developer, talks about how to implement single sourcing. He includes a discussion of tools, pitfalls to avoid, and practical steps to take.

Johnson, Tom H. and Neil E. Perlin. I'd Rather Be Writing (2006). Articles>Interviewing>Single Sourcing>Audio

Discovering Relationship Tables

Lately I’ve been creating context-sensitive help for an online application. As part of my strategy, I’ve been trying to follow Theresa Putkey’s advice in “Usability in Context-Sensitive Help.” In her article, Theresa recommends providing more than just the steps for a specific task in the context-sensitive help window. Instead, she says to show more contextual links, including answers to why, when, and who questions, because too frequently the user who searches for help may have needs outside the specific task you describe.

Johnson, Tom H. I'd Rather Be Writing (2009). Articles>Documentation>Online>Help

Lying in a Hammock, or, Having a Single Goal without a Purpose

When you live in the moment, completing the activity itself is the success. And because writing is so multifaceted in effect — the effect both on me and others — having an open purpose doesn’t limit the results. I’m not narrow-mindedly searching for a specific achievement to happen. Instead, I’m open to unconsidered possibilities, if any of those possibilities decide to unravel.

Johnson, Tom H. I'd Rather Be Writing (2009). Articles>Project Management>Planning>Writing

Tech Comm Lobotomies

Although we look at the past with embarrassment about some of our practices, we often lack the foresight to see the present with the same degree of scrutiny. Years from now, we’ll look back at what we’re currently doing and not only blush, but feel remorse and wish we could get back what we lost.

Johnson, Tom H. I'd Rather Be Writing (2009). Articles>TC>Technical Writing>History

Making Spaces in Cluttered Houses and Cluttered Lives

Putting Pedersen’s advice to practice, step one is to make a place for everything in our lives. Figure out where it belongs. Just as you can’t organize a house if you have no where to put things, you can’t organize your life if you have no way space for the activities. If something doesn’t fit, it’s time for a trip to the figurative Salvation Army (we call them Deseret Industries here). In other words, simplify.

Johnson, Tom H. I'd Rather Be Writing (2009). Careers>Project Management>Advice>Workflow

Creativity in the Workplace

Most people consider writing to be a creative endeavor, and in some situations, it certainly is. But creativity is not just associated with writing, art, and the humanities. Penelope Trunk broadens creativity to include problem solving too.

Johnson, Tom H. I'd Rather Be Writing (2009). Articles>Writing>Advice>Workplace

Is Technical Writing Boring?

While the content of what I write at work is not all that interesting, and even the paradoxes or other conundrums about technical writing sometimes dull, I really get excited about the technology side of my job. New technologies are emerging each day at a rapid rate. It’s like we’re living in the internet era before the dot.com burst. This is a Web 2.0 land, where even Google threatens to become the next operating system. I am really eager to use a wiki to write my next set of documentation.

Johnson, Tom H. I'd Rather Be Writing (2007). Articles>Writing>Technical Writing>Wikis

How to Get a Job in Technical Writing: A 7-Step Guide for Students

If you’re a college student looking to become a technical writer after you graduate, you face a formidable challenge: you can’t get a job without experience, and you can’t get experience without a job. Especially in a competitive job market, getting a job as a technical writer directly after you graduate — without a foundation of previous jobs, experience with a handful of tools, and an impressive portfolio — can be especially difficult. However, if you follow these seven steps, which are not easy, not something you can do overnight, you will find a job.

Johnson, Tom H. I'd Rather Be Writing (2009). Careers>TC>Writing>Technical Writing

The Appeal of Adobe InDesign

Working with InDesign is interesting. On the one hand, it’s not really a tool built for technical writers. It’s intended for people laying out magazines, brochures, other heavily designed print matter. As such, some things can be confusing. Cross references, figure references, a table of contents — get ready to search the help to figure these out. On the other hand, the power of the InDesign is somewhat captivating. You’re only limited by your own ignorance.

Johnson, Tom H. I'd Rather Be Writing (2009). Articles>Document Design>Software>Adobe InDesign

Information Overload: Conversation with Ricardo Amigo

Dealing with information overload can be a huge stressor in life. Not only trying to keep up with the constant deluge of information that comes at you daily, but also managing that information in an organized way — so that you can find and implement it — can put your sanity in question. In this podcast, I talk with Ricardo Amigo, a translator in Costa Rica, about different ways to manage information overload.

Johnson, Tom H. and Ricardo Amigo. I'd Rather Be Writing (2009). Articles>Interviews>Project Management>Information Design

Duct Tape Technical Writers

In reality, the user just wants a brief, clear explanation of a concept or task. The user will glance and skim — reading behaviors hardly worthy of the elitist grammarian who argues the finer points of “which” versus “that” in restrictive clauses.

Johnson, Tom H. I'd Rather Be Writing (2009). Articles>Document Design>Technical Writing>Minimalism

The Seven Deadly Sins of Blogging: Sin #3, Being Boring

Being boring is sin #3 in my list of the seven deadly sins (which include being fake, irrelevant, boring, unreadable, irresponsible, inaccessible, and inattentive). Perhaps a more tactful way of saying something is boring is to say the writer neglects to “keep the audience’s attention.”

Johnson, Tom H. I'd Rather Be Writing (2009). Articles>Writing>Blogging>User Experience

The Seven Deadly Sins of Blogging: Sin #4, Being Unreadable

Although there are other ways to increase your blog's readability, these are the most important elements to consider: font size, line height, line length, typeface, background, subheadings, paragraphs, white space, graphics, and invisibility.

Johnson, Tom H. I'd Rather Be Writing (2009). Articles>Web Design>Typography>Usability

The Seven Sins of Blogging, Sin #6, Being Unfindable

How can you enable readers to naturally find the content in your archives? How can you make the hundreds of posts you write more visible and prominent, especially if readers are looking for it? This is partly what the field of findability is all about. You can implement several easy aggregation techniques to increase the findability of your content. You can add tags and categories to your posts, and readers can navigate your content this way.

Johnson, Tom H. I'd Rather Be Writing (2009). Articles>Web Design>Blogging>Search Engine Optimization

The Seven Deadly Sins of Blogging: Sin #5, Being Irresponsible

As you blog, remember that you have a relationship with your readers -- a relationship that requires you to disclose any important information, especially monetary, that might bias your views. Don't ruin relationships with those around you by revealing private details of their lives without approval. Ensure you don't represent your company in a negative light. And choose balanced, honest posts rather than sensationalism.

Johnson, Tom H. I'd Rather Be Writing (2009). Articles>Writing>Blogging>Professionalism

A Few Surprises in Using a Wiki for Documentation

Recently I’ve been working on a simple calendar project that uses a wiki for documentation. Although I’ve heard a lot about using wikis for documentation, and have even used them in the past, I ran into a few surprises this time.

Johnson, Tom H. I'd Rather Be Writing (2009). Articles>Documentation>Content Management>Wikis

The Seven Deadly Sins of Blogging: Sin 7, Being Inattentive

One appealing aspect of blogs over print media is the ability to comment and respond to comments. It’s the appeal of a conversation instead a lecture.

Johnson, Tom H. I'd Rather Be Writing (2009). Articles>Web Design>Blogging>Collaboration

Wikis and the Holy Grail of Content Independence

The concept of having control over your help content, to update it at any time, is what I’m calling content independence. Establishing content independence in your publishing environment may be a battle that can take years. For example, at a previous job, it took five years to finally convince architecture that we needed and deserved our own independent folder on a production server. In my current situation, I’ve pursued publishing routes in infrastructure that would enable on-the-fly updating, but for two years in a row I’ve come up empty-handed. With wikis, I think I’ve finally found the holy grail of content independence.

Johnson, Tom H. I'd Rather Be Writing (2009). Articles>Content Management>Single Sourcing>Wikis