I'd Rather Be Writing » Adobe Indesign

The Case of the Stolen Documentation

Tom Johnson — Wed, 06 Jan 2010 07:14:44 +0000

Some months ago I created a half a dozen quick reference guides for an application that would have a potential audience of thousands of users (after it cleared the beta phase). The size of the audience gave me hope that I would actually create documentation to be used by more than a handful of people outside the internal workings of my organization.

I created the guides in Adobe InDesign because it seemed to make sense for the situation — the application was relatively simple, and there were just a few roles. I crafted the layout and design carefully, branding the guides with the same color and feel as the application. I meticulously ensured each task was described with concision and accuracy, and I limited the text for each guide to one double-sided page to avoid intimidating the users. During each application update, I reviewed the guides against the new use cases and updates and made sure the instructions matched the new functionality.

As you know, I’ve given several presentations about quick reference guides and have written about them numerous times on my site, even calling quick reference guides the poetry of technical writing. These six guides were my poems. I felt a sense of pride with them and displayed them in my gallery of quick reference layouts and during team meetings.

And then one day, I received a phone call. One of the clients asked for the source files so she could update them herself (or have other designers update the source files under her department’s supervision).

The source files? I said. They’re in Adobe InDesign.

Yes, please send the originals, she said. I felt a bit offended. No one ever asked me for source files before. I wondered what it was she wanted to update that I couldn’t do. Wasn’t I close to the engineers and project managers, and therefore in a better position to update the documentation? Wasn’t I keeping it all up to date?

But I know I work for an organization, and the products I make don’t belong to me. So I zipped them up and clicked Send. For a long time, that was the last I ever saw of them.

I hung around a couple of project meetings after that, but it was clear that the documentation was now owned by someone else. I was no longer needed. Okay, I said, and moved on to other projects.

For a couple of weeks I felt upset and confused. I didn’t know if I should periodically inspect their updates, if I should close the project entirely, or what. I laid low and continued to work on other projects.

No more emails, no more requests, no more maintenance. It felt as if my documentation was stolen.

Blog Sponsors

Adobe InDesign and Transparent Images on Color Backgrounds

Tom Johnson — Tue, 31 Mar 2009 04:04:34 +0000

When you insert a transparent image over a color background in Adobe InDesign, the transparent image may look good when you generate the PDF, but when you actually print the image from a laser printer, the transparent image has a faint background where the image should otherwise be transparent.

I spent a long time trying to figure out the solution to this problem. It seemed to be a new, unheard of issue by everyone I asked. But after a post to an InDesign forum, I found the answer.

InDesign Secrets calls it “Yucky Discolored Box Syndrome.” Here’s their solution:

Create a Transparency Flattener Preset that completely rasterizes everything:

Edit > Transparency Flattener Presets, click on “High” as a starting point, and then click “New.”

In the ensuing dialog box, yank the raster/vector slider all the way to the left. Set the linework resolution to the printer’s res (say, 600), and set the gradient/mesh resolution to, oh, 150. (I think you’ll find shadow appearance satisfactory at 150. If not, go to 300.) Save as a new Flattener Preset.

File > Print, and under Output, choose Composite CMYK, and CHECK the “Simulate Overprint” checkbox. Under Advanced, select your all-raster flattener.

Blog Sponsors

Quick Reference Guides: The Poetry of Technical Writing

Tom Johnson — Sun, 06 Jul 2008 22:27:13 +0000

How many times have you written a 75+ page guide and heard the customer say, This is great, but can you give us a condensed version?

After the third or fourth time I’d heard this, I decided to actually try it. I wasn’t sure exactly how to lay it out, so I spent a couple of days flipping through magazines — especially WIRED — looking for attractive layouts to copy.

I also needed a better tool than Word, and managed to acquire a copy of Adobe InDesign. After a few days of prototyping and writing, I finished my first one-page quick reference guide.

At the next project meeting, I brought color copies of this one-page version of instructions. The response was overwhelming. You’d think I was handing out free candy. Everyone wanted one.

They immediately started looking it over. In contrast to the pained expressions I’d seen after handing people long manuals, their faces showed incalculable glee. At that point, I knew the quick reference guide was a must-have deliverable for every one of my projects.

The names can vary — “Cheat Sheet,” “Getting Started,” “Fast Track,” “Job Aid” — but the concept is the same. Condense the most important information into one double-sided page. By “condense” I don’t mean shrink the font to 6 pt., decrease the leading, and eliminate all white space. With the quick reference guide, you take something that’s robust and complex, and distill it down to its essence, but distill it in a way that brings perfect clarity to users. Quick reference guides are like the poetry of technical writing.

Part of the appeal of quick reference guides is the close way they model software learning. Almost invariably, when people need to learn an application, they follow this same pattern:

They sometimes read a little bit about the product (maybe 2-3 minutes).
They open the product and see if it’s intuitive to figure out without the manual.
When they get stuck, they turn to the help for information about a specific task.

The quick reference guide serves the user’s needs in step 1. Arguably, many people don’t even complete step 1, and just dive straight into the application. Still, having a one-page guide to quickly refer to while stumbling around the user interface for the first time can be helpful.

Other than brevity, how then are quick reference guides like poems? It’s more than just being concise. With poetry, the poet attempts to evoke a mood or paint a moment, and in that brief moment, capture the entire essence of something. Here’s an example of one of my favorite poems, “Lying in a Hammock at William Duffy’s Farm in Pine Island, Minnesota,” by James Wright.

Over my head, I see the bronze butterfly
Asleep on the black trunk,
Blowing like a leaf in green shadow.
Down the ravine behind the empty house,
The cowbells follow one another
Into the distances of the afternoon.
To my right,
In a field of sunlight between two pines,
The droppings of last year’s horses
Blaze up into golden stones.
I lean back, as the evening darkens and comes on.
A chicken hawk floats over, looking for home.
I have wasted my life.

In 13 lines, the poet has captured the entire essence of a lazy summer. The last line in particular, “I have wasted my life,” contains levels of depth.

Writing a quick reference guide is much the same effort. It’s not that you merely cut words to give a shorter manual, but that you try to compress the manual and express in its five-word equivalent.

I’ll grant that the task is probably impossible for technical material. Still, the attempt is there. The philosophy remains the same. Teach us how to use this manual in 5 minutes rather than 5 hours. It’s a philosophy of simplification and linguistic efficiency.

Many people think that the relationship between brevity and obscurity trends in the following direction.

In other words, as your writing becomes more brief, the level of obscurity increases. Actually, a good quick reference guide that does the job in a minimalistic way can have the opposite trend: becoming less obscure as the brevity increases.

This is because, simply put, no one reads the big manual. If you force the reader to wade through hours of preliminary text — a table of contents, table of figures, preliminary legal jargon, explanations of icons and style notations, introductory pages, lists of file menus, tab menus, icon meanings, and so on, before even getting to an actual task — the reader’s patience times out long before the manual ever teaches them something. I remember one time I was reading an AuthorIt manual. I’d reached page 87 and still didn’t see a single how-to task.

You don’t want to focus on too much in a quick reference guide. Remember, the poet focuses on a telling moment, and doesn’t narrate the whole of history. Likewise, the scope of a quick reference guide focuses on core tasks — tasks that are representative of the application as a whole.

Also, don’t be deceived by the brevity and scope of the quick reference guide. In wrangling with layout, scope, and concision, you might spend several days writing just one page. But when you’re done you can practically hang it on your cube wall.

A good layout tool is handy when creating quick reference guides. Adobe InDesign is a powerful tool, but you could probably make do with any program you’re familiar with. Here’s a sample quick reference guide template (an Indesign .indd file) that I sometimes start with, and then modify to best fit the help content.

If you have any sample quick reference guide layouts that you like, I’d love to hear about them.

Update: For more information on quick reference guides, see my list of other posts and templates on quick reference guides here.