Skip to main content

Author: Alan Pringle

Opinion

Unedited content will get you deleted

flickr: Nics events

The abundance of information today forces content consumers to filter out redundant and unworthy information—much like an editor would. That, however, doesn’t mean content creators can throw up their hands and send out unreviewed content for readers to sort through. Instead, authors (and particularly their managers) need to understand how editing skills can ensure their information doesn’t get filtered out:

[A]re we getting any better at editing in a broader context, which is editing ourselves? Or to rephrase it, becoming a better critic of our own work? Penelope Trunk (again) lists the reasons why she works with an editor for whatever she writes in public:

  • Start strong – cut boring introduction
  • Be short – and be brave
  • Have a genuine connection – write stuff that matters to the readers
  • Be passionate – write stuff that matters to you
  • Have one good piece of research – back your idea up

They have one thing in common: difficult to do on our own.

Granted, some of those bullet points don’t completely apply to technical writing, but it is hard to edit your own work, regardless of the kind of content. For that very reason, folks at Scriptorium get someone else to review their writing. Whether the content is in a proposal, book, white paper, important email to a client, or a blog post, we understand that somebody else’s feedback is generally going to make that information better.

The same is true of technical content. A lot of documentation departments may no longer hire dedicated editors, so peer reviewers handle editing tasks. Electronic review tools also make it easier than ever to offer feedback: even a quick online review of content by another writer will likely catch some potentially embarrassing typos and yield suggestions to make information more accessible to the end user. (You can read more about the importance of editing in a PDF excerpt from the latest edition of Technical Writing 101.)

With so much competing information out on the Internet, companies can’t afford to have their official documentation ignored because it contains technical errors, misspellings, and other problems that damage the content’s credibility. Even if you don’t have the time or budget for a full-blown edit, take just a little time to have someone do a quick technical review of your work. Otherwise, end users seeking information about your product will likely do their own editing—in their minds, they’ll delete you as a source of reliable information. And that’s a deletion that’s hard to STET.

PS: Software that checks spelling and grammar is helpful, but it’s not enough: it won’t point out technical inaccuracies.

Read More
News Opinion

Are you ready for mobile content?

A report from Morgan Stanley states that mobile Internet use will be twice that of desktop Internet and that the iPhone/smartphone “may prove to be the fastest ramping and most disruptive technology product / service launch the world has ever seen.” That “disruption” is already affecting the methods for distributing technical content.

With users having Internet access at their fingertips anywhere they go, Internet searches will continue to drive how people find product information. Desktop Internet use has greatly reshaped how technical communicators distribute information, and having twice as many people using mobile Internet will only push us toward more online delivery—and in formats (some yet to be developed, I’d guess) that are compatible with smaller smartphone screens.

The growing number of people with mobile Internet access underscores the importance of high Internet search rankings and a social media strategy for your information. If you haven’t already investigated optimizing your content for search engines and integrating social media as part of your development and distribution efforts, it’s probably wise to do that sooner rather than later. Also, have you looked at how your web site is displayed on a smartphone?

If you don’t consider the impact of the mobile Internet, your documentation may be relegated to the Island of Misfit Manuals, where change pages and manuals in three-ring binders spend their days yellowing away.

Read More
DITA Webinar

2010: A DITA Odyssey

When you’re considering tools for authoring DITA content and creating output, there are many choices to evaluate. To make your journey toward DITA implementation easier, Scriptorium is offering free webinars in early 2010 to show you how three tools handle DITA-based information.

Odysseus in front of Scylla and Charybdis by Johann Heinrich Füssli (Wikipedia)

Odysseus in front of Scylla and Charybdis by Johann Heinrich Füssli (Wikipedia)

On January 19, Sarah O’Keefe will show you how MadCap Flare supports DITA constructs, and on February 16, Simon Bate will demonstrate the DITA features in the oXygen XML editor. On March 16, Scott Prentice of Leximation will demonstrate how the DITA-FMx plugin works with FrameMaker 9.

As an added bonus, attendees can win a free license of the tool shown during each demo! For more information about these sessions and to register, visit our events page.

If there are other topics you’d like to see covered in later free webcasts, please send suggestions to [email protected].

Read More
Opinion

Would you use just a gardening trowel to plant a tree?

As technical communicators, our ultimate goal is to create accessible content that helps users solve problems. Focusing on developing quality content is the priority, but you can take that viewpoint to an extreme by saying that content-creation tools are just a convenience for technical writers:

The tools we use in our wacky profession are a convenience for us, as are the techniques we use. Users don’t care if we use FrameMaker, AuthorIt, Flare, Word, AsciiDoc, OpenOffice.org Writer, DITA or DocBook to create the content. They don’t give a hoot if the content is single sourced or topic based.

Sure, end users probably don’t know or care about the tools used to develop content. However, users do have eagle eyes for spotting inconsistencies in content, and they will call you out for conflicting information in a heartbeat (or worse, just abandon the official user docs altogether for being “unreliable”). If your department has implemented reuse and single-sourcing techniques that eliminate those inconsistencies, your end users are going to have a lot more faith in the validity of the content you provide.

Also, a structured authoring process that removes the burden of formatting content from the authoring process gives tech writers more time to focus on providing quality content to the end user. Yep, the end user doesn’t give a fig that the PDF or HTML file they are reading was generated from DITA-based content, but because the tech writers creating that content focused on just writing instead of writing, formatting, and converting the content, the information is probably better written and more useful.

Dogwood // flickr: hlkljgk

Dogwood // flickr: hlkljgk

All this talk about tools makes me think about the implements I use for gardening. A few years ago, I planted a young dogwood tree in my back yard. I could have used a small gardening trowel to dig the hole, but instead, I chose a standard-size shovel. Even though the tree had no opinion on the tool I used (at least I don’t think it did!), it certainly benefited from my tool selection. Because I was able to dig the hole and plant the tree in a shorter amount of time, the tree was able to develop a new root system in its new home more quickly. Today, that tree is flourishing and is about four feet taller than it was when I planted it.

The same applies to technical content. If a tool or process improves the consistency of content, gives authors more time to focus on the content, and shortens the time it takes to distribute that content, then the choice and application of a tool are much more than mere “conveniences.”

Read More
Opinion

Don’t forget localization

I was reading a list of seven tips for improving technical writing, and the first tip gave me pause:

1. Analogy – provide a comparison or analogy to describe how something abstract works.

Not everyone is as familiar with the system as you are. Try to help the reader along by giving as much direction as possible so they see the bigger picture.

Once they understand how the system works at a high level, they will have more confidence in reading the more technical details.

If your content is going to be localized, comparisons and analogies are going to be problematic because they are often culturally specific. Here’s a good example of how an analogy had to be changed in marketing material so that it made sense to audiences in different parts of the world:

When the Walt Disney World Resort created promotional material for a North American audience, it stated that the resort is 47 square miles or “roughly half the size of Rhode Island.”

Outside of North America, many people don’t know about Rhode Island, and this analogy would have no meaning. Walt Disney wisely chose to customize the material for each target market. For instance, in the UK version, the material states that the resort is “the size of greater Manchester,” and in Japan, the resort is described as the size of the subway system.

Disney may have the deep pockets to pay for rewriting marketing content for various audiences, but I suspect there are few technical documentation departments these days that have the money or resources to reformulate analogies for different regions. You’re better off avoiding analogies altogther when writing technical content.

Read More
Opinion

Font snobbery? (I don’t think so.)

For its 2010 catalog, IKEA used Verdana font instead of the customized Futura it’s used for years. To say people noticed the switch would be an understatement:

“Ikea, stop the Verdana madness!” pleaded Tokyo’s Oliver Reichenstein on Twitter. “Words can’t describe my disgust,” spat Ben Cristensen of Melbourne. “Horrific,” lamented Christian Hughes in Dublin. The online forum Typophile closed its first post on the subject with the words, “It’s a sad day.” On Aug. 26, Romanian design consultant Marius Ursache started an online petition to get Ikea to change its mind. That night, Verdana was already a trending topic on Twitter, drawing more tweets than even Ted Kennedy.

As a fan of IKEA and its products, I can understand the reaction. If you showed me a page out of an IKEA catalog with just text and prices (and no pictures or funky product names, of course!), I could tell you in a heartbeat that the content was from IKEA.

Verdana may be easier to read if you’re looking at the IKEA catalog online, but that font lacks the designer-y flair of Futura. Because IKEA is known for its affordable cutting-edge design, Verdana just doesn’t seem to quite fit the bill.

This situation reminds me of a comment a friend made about a failed hotel in Raleigh, NC. He said, “Did you see the awful Brush Script on the hotel’s sign? Those people clearly didn’t know how to run a business.” I doubt the Brush Script killed the hotel, but that bad design decision gave my friend (and probably many others) a very unfavorable impression about the company.

Earlier this week, Sarah O’Keefe and I were doing some web research and came upon a web site that used Comic Sans. My reaction to that site was less than positive. I loathe Comic Sans, and I find it hard to take any company seriously that uses a font that emulates text in a comic book.

A company’s use of fonts can become iconic–think about the fonts used by Coca-Cola and FedEx in their logos, for example. Font choice does have an effect on how people perceive content, a product, or a company.

I don’t think reactions to fonts are limited to just those who work in publishing and design. No snobbery here at all. (But if noticing fonts makes me a card-carrying font snob, you better believe that card would have no Comic Sans on it.)

For more about the impact of fonts, check out the documentary Helvetica:

Read More
Opinion

In defense of English majors: we can understand business issues, too

In his latest blog entry, Neil Perlin explains how important it is for technical writers to have an understanding of business issues. With such knowledge, they can contribute to cost justifications for decisions that affect them directly. I couldn’t agree more with that. It is absolutely in writers’ best interests (and a matter of self-preservation) to understand processes and costs.

I strongly disagree, however, with the following assertion:

Writers from fine arts or English backgrounds can rarely discuss cost-justification in finance terms, so they have little input on buying decisions.

I am an English major, and I freely admit I am more of a “words” person than a “numbers” person. That being said, I am no slouch in the finance department. (Calculus is another matter, though.) I know many people with degrees in English and the liberal arts who are quite adept at understanding The Big Picture and developing business cases. Lumping all of us into a “can rarely discuss cost-justification” group is unfair.

Now I need to remind myself not to group software developers into a “can rarely write a coherent procedure” category. (It’s easy to make generalizations when you’re not the target of them.)

Read More
Humor

Lost in translation (and in my brain)

Last night, a bit of spam managed to worm its way through the filters on a personal email account, and I have to admit I glanced at the content while scanning previews of messages. That’s when I spotted a paragraph that really jumped out at me:

They have good management systems, product quality inspection system. And international speedboat (EMS) is the door – door accurate! Soon!

My thought process was, What’s up with the international speedboats? And why are emergency medical services (EMS) using these speedboats? I knew that the person who wrote the content was likely not a native English speaker, but I could not figure out what the writer was trying to communicate.

This morning, I finally realized what the message was trying to say: the company uses EMS worldwide delivery services for prompt and accurate delivery to my door. My brain must not have been firing on all cylinders last night when I thought EMS meant “emergency medical services.”

I don’t think I’ve ever spent as much time thinking about a company’s marketing message, but my thoughts weren’t about using the company’s services–I was merely trying to comprehend the message itself. That’s not what the company intended, I’m sure.

Marketing for a global audience–particularly one that associates EMS with “emergency medical services”–is not an easy thing!

Read More
Opinion

Error message melodrama

The Shanghai Tech Writer blog has posted a screen capture of a rather ominous error message in FrameMaker:

The licensing subsystem has failed catastrophically. You must reinstall or call customer support.

I have never been the unfortunate recipient of that particular message in the many years I’ve worked with FrameMaker. If I did encounter that message, I would fully expect it to be accompanied by the shrieking strings from the Psycho shower scene. The use of “catastrophically” is a bit over the top. The fact I need to reinstall or contact customer support sets the tone enough, thank you very much–no soundtrack or scary adverb required.

The editor in me wants “catastrophically” removed from that message. If that bit of text came across my desk for review, I would have pushed back hard on the use of that word. It’s bad enough the user has to get a solution to the error, and referring to the problem as “catastrophic” is certainly not doing the user any favors.

Read More
Opinion

Our first experience with print on demand (POD)

It’s been a little over a month since we released the third edition of Technical Writing 101. The downloadable PDF version is the primary format for the new edition, and we’ve seen more sales from outside the U.S. because downloads eliminate shipping costs and delays.

Selling Technical Writing 101 as a PDF file has made the book readily available to a wider audience (and at a cheaper price of $20, too). However, we know that a lot of people still like to read printed books, so we wanted to offer printed copies—but without the expense of printing books, storing them, and shipping them out.

We have published several books over the past nine years, and declining revenue from books made it difficult for us to justify spending thousands of dollars to do an offset print run of 1000+ copies of Technical Writing 101 and then pay the added expense of preparing individual books for shipment as they are ordered. Storage has also been a problem: we have only so much space for storing books in our office, and we didn’t want to spend money on climate-controlled storage for inventory. (Book bindings would melt and warp without air conditioning during our hot, humid summers here in North Carolina.) For us, the logical solution was print on demand (POD): when a buyer orders the book, a publishing company prints a copy using a digital printing process and then ships it.

We chose Lulu.com for our first experiment with POD, and so far, we have been happy with the quality of the books from there. We are still exploring our options with POD and may try some other companies’ services in the future, but based on our experience so far, I can offer two pieces of advice:

  • Follow the specs and templates provided by the printer, and consider allowing even a bit more wiggle room for interior margins. The first test book I printed had text running too close to the binding, so I made some adjustments to add more room for the interior margins before we sold the book to the public.
  • Look at the page sizes offered by the different POD publishers before choosing a size. If you choose a page size that multiple POD publishers support, you’ll have more flexibility in using another publisher’s services in the future, particularly if they offer other services (distribution, etc.) that better suit your needs. Also, ensure the page size you choose is supported when printing occurs in a country other than your own; some publishers have facilities and partners in multiple countries. In an attempt to minimize the amount of production work for the third edition, I chose a page size for Technical Writing 101 that was the closest match to the footprint of the previous edition’s layout. However, I likely would have chosen a different page size if I had known more about the common sizes across the various POD companies. The page size I chose at Lulu is not supported by CreateSpace, which is Amazon’s POD arm. When you publish through CreateSpace, you get distribution through Amazon.com, which isn’t the necessarily the case with other POD publishers. (I’ve read several blog posts about how some authors use the same sets of files to simultaneously publish books through multiple POD firms to maximize the distribution of their content.)

In these tight economic times, POD publishing makes a lot of sense, particularly when you want to release content in print but don’t want to invest a lot of money in printing multiple copies that you have no guarantee of selling. The POD model certainly was a good match for Technical Writing 101, so we decided to give it a try.

I’ll keep you updated on our experiences with POD publishing in this blog. If you have experience with POD, please leave a comment about how it’s worked for you.

Read More