It can be a mightily sucktacular experience when you discover what other people think technical communicators do.
Author Archive
When perceptions bite tech comm’s backside
May 11th, 2012 by Alan Pringle
Kindle hasn’t killed the print star—yet
May 4th, 2012 by Alan Pringle
Kindle sales will cannibalize print sales.
Hug it out with your IT department: collaboration beyond content
April 9th, 2012 by Alan Pringle
The stereotypical technical writer working in isolation is an endangered species—if not already extinct.
And the ebook survey winners are EPUB, Kindle, and … Kai Weber!
February 29th, 2012 by Alan Pringle
Thanks to everyone who participated in our survey about ebooks on technical communication topics. We had 78 respondents complete the survey, and Kai Weber won the drawing for the $50 gift certificate from amazon.com. Congratulations, Kai!
Unmasking the lizards in tech comm
February 21st, 2012 by Alan Pringle
In the 1983 and 2009 versions of the TV series V, human-looking aliens visit Earth. It turns out those aliens are unfriendly reptilian creatures lurking beneath human shells. Of course, there are dramatic reveals that expose the aliens for what they really are.
Answer seven (or fewer) questions about ebooks to win $50
February 6th, 2012 by Alan Pringle
Recent news about two new ebook formats has made ebook distribution even more challenging for publishers. To gain some clarity on the market for ebooks about tech comm (and to keep ourselves from repeatedly banging our heads against the wall), we’re asking for your input on ebook editions and devices.
“Trust me” isn’t a business plan
January 30th, 2012 by Alan Pringle
Knowing you can rely on someone is vital to professional relationships. But when it comes to proposing process change, the words “trust me” are never, ever enough.
Another peril in ebook publishing: Amazon KF8 compatibility
January 24th, 2012 by Alan Pringle
KF8. Nope, it’s not K2‘s long-lost mountain cousin. It’s Amazon’s new ebook format.
While dealing with this new format probably isn’t as daunting as scaling a 28,251 ft. mountain, KF8 is providing a particularly bothersome challenge right out of the gate: it’s not compatible with any Kindle devices other than the Kindle Fire!
(more…)
Drink me: starting small like Alice
January 9th, 2012 by Alan Pringle
“What a curious feeling!” said Alice; “I must be shutting up like a telescope.”
And so it was indeed: she was now only ten inches high, and her face brightened up at the thought that she was now the right size for going though the little door into that lovely garden.
Lewis Carroll in Alice’s Adventures in Wonderland
Do as a politician does (but just this once!)
December 14th, 2011 by Alan Pringle
My cynical streak makes me very leery (and often weary) of what politicians say and do, particularly around election time. But an article about President Obama’s re-election strategy really resonated with me—mostly because it offers some insight into what we should be doing in technical communication right now.
Joining Sally Field’s “like me” revolution
December 7th, 2011 by Alan Pringle
In 1985, a few eyebrows were raised (and many eyes rolled) when Sally Field gave her “You like me!” Academy Award acceptance speech.
(Non)predictions for 2012
November 30th, 2011 by Alan Pringle
With 2011 waning, people are contemplating what 2012 will bring for technical communication. Our profession is changing rapidly, so intelligent conversations about the future of tech comm are essential.
All that smart talk has absolutely nothing to do with this post.
(more…)
It’s Adobe’s party, and we’ll cry if we want to
November 17th, 2011 by Alan Pringle
I had a lot fun meeting all the great tech comm folks who attended LavaCon in Austin earlier this week. (I’m also dreaming about the next time I’ll get a divine Buffalo Bill burger from Hopdoddy.) (more…)
Banishing our black berets
October 6th, 2011 by Alan Pringle
In my junk mail, the capital letters were screaming in bright red: WE’RE NOT ARTISANS. (more…)
Spinning tech comm improvements into marcomm strategies
September 19th, 2011 by Alan Pringle
This morning, I was among the many who received an email from Netflix CEO Reed Hastings. He was responding to criticisms that Netflix “lacked respect and humility in the way [the company] announced the separation of DVD and streaming and the price changes.” (more…)
The latest style for tech comm: adding value
July 25th, 2011 by Alan Pringle
Over the weekend, a friend showed me an episode of a reality show that featured some commentary by a “style expert.” This expert offered his advice while dressed in an outfit that would work well as a costume in a production of Oliver Twist (and that’s being charitable).
Win our Big Design giveaways—even if you’re not attending!
July 14th, 2011 by Alan Pringle
Today, Sarah O’Keefe and Ryan Fulcher are on their way to the Big Design 2011 conference in Dallas. If you’re attending the conference, drop by Scriptorium’s space in the exhibition area tomorrow. (Just look for the bright yellow banner with the duckling on it!) (more…)
Early-bird discount on our Structured Authoring report
June 27th, 2011 by Alan Pringle
Can’t decide whether structured authoring is right for your organization? Curious about the costs and necessary effort? Our latest publication, The State of Structured Authoring, is for you. (more…)
STC Summit virtual booth: enter Wednesday’s drawing for The DITA Style Guide
May 18th, 2011 by Alan Pringle
Today is the last day for our STC Summit virtual booth. You can win a copy of The DITA Style Guide by entering the final drawing: (more…)
STC Summit virtual booth: enter Tuesday’s drawing for The DITA Style Guide
May 17th, 2011 by Alan Pringle
Welcome to the second day of our STC Summit virtual booth! You can win a copy of The DITA Style Guide by entering today’s drawing: (more…)
STC Summit virtual booth: enter Monday’s drawing for The DITA Style Guide
May 16th, 2011 by Alan Pringle
Welcome to the first day of our STC Summit virtual booth! You can win a copy of The DITA Style Guide by entering today’s drawing: (more…)
Win The DITA Style Guide at our STC Summit booth (and virtual booth)
May 13th, 2011 by Alan Pringle
If you’re going to the STC 2011 Summit next week in Sacramento, be sure to drop by Scriptorium’s booth in the exhibition hall. You can chat with Sarah O’Keefe and Simon Bate about the tech comm challenges you’re facing, and you can see demos of our PDF and web help plugins for the DITA OT. (more…)
Video has not killed the tech comm star
April 20th, 2011 by Alan Pringle
Ellis Pratt of Cherryleaf asks: How important is video to technical authors?
Graham argues you cannot afford to ignore video. (more…)
Buy The DITA Style Guide in print (and with a 43 percent discount!)
March 7th, 2011 by Alan Pringle
I’m pleased to announce that Tony Self’s new book, The DITA Style Guide, is now available in print. The book is beginning to filter into the listings of online bookstores.
At the moment I wrote this blog entry, bn.com was offering the book for $20.38, which is a whopping 43 percent off the $35.95 cover price. (more…)
The DITA Style Guide: going to the printer this week
February 23rd, 2011 by Alan Pringle
Tony Self and the team at Scriptorium have almost wrapped up work on the print edition of Tony’s book, The DITA Style Guide. (Excuse me while I do a private happy dance.) We plan to submit the files to the printer this week, which means the book will be available at online bookstores around the second week of March. Stay tuned for information on the ePub edition, which will come out shortly after the print edition. (more…)
From ePub to Kindle: Technical Writing 101 now has a Kindle edition
February 14th, 2011 by Alan Pringle
We just released the Kindle edition of Technical Writing 101. You can download the Kindle edition instantly from amazon.com or amazon.co.uk. You can also get a free sample if you want to try before you buy.
Contemplating the tablet in tech comm
February 1st, 2011 by Alan Pringle
Ebooks and tablets are helping people read more than they did before: in a recent survey, 66 percent of portable device owners said they were reading more.
That statistic should prompt all technical communicators to think about if—and how—ebooks and other tablet-compatible formats (including apps) fit into their content delivery. (more…)
Social media: marketing in every message
January 26th, 2011 by Alan Pringle
Social media has transformed the work of technical communicators, but we’re far from alone in feeling its impact: (more…)
Writers can make good publishers
January 7th, 2011 by Alan Pringle
Earlier this week, Richard Curtis at e-reads asked Do Authors Make Good Publishers?, and he answers the question emphatically in the first paragraph of his post:
The answer is No. (more…)
An update on The DITA Style Guide: it’s in technical review
December 16th, 2010 by Alan Pringle
Here’s a quick update on Tony Self’s upcoming book, The DITA Style Guide. (more…)
Failure to communicate: fatal to projects (and political parties)
December 6th, 2010 by Alan Pringle
Over the weekend, I was catching up with a friend I hadn’t seen since the mid-term elections here in the US. While hashing out what the election results meant, my friend said that he felt that history would be kinder to the accomplishments of Congress than the electorate was.
(more…)
Distilling 20 years of tech comm into eight words of advice
October 4th, 2010 by Alan Pringle
Last month marked my 20th year working in technical communication. (Please send all congratulatory pastries and chocolates to Scriptorium’s offices. Thank you!)
Retail therapy for tech comm (and I don’t mean shopping)
August 4th, 2010 by Alan Pringle
“She’s stupid.”
That’s what a shopper recently said about a coworker’s daughter, who is working a part-time retail job. (more…)
Increase your DITA literacy with The DITA Style Guide
June 18th, 2010 by Alan Pringle
To help technical communicators get a grasp on all the elements and attributes in DITA, Scriptorium Press will publish The DITA Style Guide: Best Practices for Authors by Tony Self, founder of Hyperwrite and chairperson of the OASIS DITA Help Subcommittee. (more…)
Interview with a vampire: interviewing to find processes that drain efficiency
June 3rd, 2010 by Alan Pringle
When you’re considering an overhaul of your publishing workflow, you may find yourself becoming a metaphorical version of Van Helsing, the vampire-hunting character from Bram Stoker’s Dracula (and the many, many movies based on the Dracula story). You need to find all the efficiency-draining aspects of your current process and eliminate them.
Fortunately, you don’t have to arm yourself with wooden stakes while lurking around graveyards at sundown to find those inefficiencies. Instead, you can rely on interviews conducted in the comfort of an office.
In his Core Dump blog, Keith Soltys reposted excellent advice from Seth Park about choosing a CMS system. The advice, however, applies to any process change, particularly the second point in the list:
Start with your requirements, starting with your users. If you’re going to be changing the way people work, you are signing up for several years of hearts-and-mind campaigning. Make sure that (in addition to your compulsory OS requirements, editor integration, publication system integration, etc.) you’ve thought through each and every way each user will touch the system.
Interviewing team members working in the current process (and in the new one) is an excellent way to get information about requirements—and the inefficiencies you need to eliminate during the changeover.
The benefits of interviews are twofold: they provide management with an excellent opportunity to learn about how things really operate, and they also give team members the chance to offer input on how to reshape the workflow. Switching over to a new process goes much more smoothly when all team members have the opportunity to contribute. (You can read more about managing process change in a post I wrote earlier this year.)
So, who should handle the interviewing? If it all possible, hire a consultant. (As Seth Park mentions in his CMS advice, “Don’t be afraid of a reputable consultant.”) Having a third party conduct the interviews—perhaps as part of an assessment of your current workflow and the modifications that would increase efficiency—may lead to more honest answers than if a member of management asked the same questions. Also, a consultant will likely have more experience in asking the right kinds of questions based on previous experience with other process implementations.
To keep expenses down, the consultant can conduct the interviews through web meetings and phone calls. If you just don’t have the budget to hire a consultant, consider drawing up a list of questions and then asking someone outside of your department to help with the interviews. You could also implement an online survey through a web-based tool such as SurveyMonkey.
Choosing new tools and processes is always daunting: dealing with new technology is challenging enough, but you also have to consider how those who work in the process will handle the changes. Taking the time to ask team members about your workflow and how to improve it can yield some very positive results—and expose the inefficiencies that are causing your workflow to bleed both time and money.
Related but gratuitous video clip: At the age of eleven, I made the mistake of taking a peek at the 1979 version of Dracula while it was running on HBO. The following brief scene, which features Laurence Olivier as Van Helsing, gave me nightmares for years to come. If catacombs, rats, and vampires scare you, don’t watch the clip. Consider yourself forewarned.
It’s Technical Writing 101′s birthday, but YOU can get the gift of a free copy
May 11th, 2010 by Alan Pringle
It’s been a year since we released the third edition of Technical Writing 101, and I’d like to thank readers for offering us positive feedback on the new edition. I have to admit it’s gratifying to read comments such as this one from Peg Mulligan:
The discussions on Structured Authoring with XML, and Web 2.0 and Technical Documentation, are among the most concisely written, best stand-alone explanations that I have seen on these subjects.
To celebrate the third edition’s first birthday, we’re giving away a printed copy. Also, we have just five copies left of the second edition, and we will give the winner one of those copies, too. It will soon be a collector’s edition! (Yeah, right.)
The contest ends on Wednesday, May 26, so enter soon!
We owe special thanks to the many instructors who have used the book to educate new technical writers. If you teach technical writing and would like to review Technical Writing 101 for your classes, contact us at books@scriptorium.com.
Can’t make it to the STC Summit? Visit our virtual booth to win goodies!
April 26th, 2010 by Alan Pringle
Sarah O’Keefe and Matt Arnold will be representing Scriptorium at the STC Summit in Dallas next week. If you’re attending the conference, be sure to visit our booth to meet Sarah and Matt, pick up some chocolate, and get a free copy of our updated white paper compilation, The Compass (while supplies last).
If you’re not attending the STC Summit, you still have a chance to pick up conference swag from us by visiting our virtual booth—a short survey that asks the same questions we ask conference attendees. During the survey, you can also ask us questions about any challenges you’re facing with developing and distributing technical content.
Complete the survey by May 5th (the day the STC Summit ends), and we’ll enter you into a drawing to win one of six copies of The Compass—and the winners get some chocolate, too. No Scriptorium conference booth would be complete without chocolate!
I’m not attending the conference, either, so you can consider me your virtual host at the virtual booth. I’ll “see” you there! (And you better hope I don’t eat all the chocolate before you get there.)
P.S. If you are attending the conference, you can see Sarah at three events:
Some Friday fun: tech writing in movies
April 16th, 2010 by Alan Pringle
Here’s a movie montage I found on YouTube featuring scenes of characters either offering or reading procedures:
Enjoy!
Cardinal sin of blog (and technical) writing: making the reader feel stupid
March 23rd, 2010 by Alan Pringle
Want to get me riled up? You can easily achieve that by making me feel stupid while reading your blog.
I read a lot of blogs about technology, and I’ll admit that I’m on the periphery of some of these blogs’ intended audiences. That being said, there is no excuse for starting a blog entry like this:
Everyone’s heard of Gordon Moore’s famous Law, but not everyone has noticed how what he said has gradually morphed into a marketing message so misleading I’m surprised Intel doesn’t require people to play the company jingle just for mentioning it.
Well, I must not be part of the “everyone” collective because I had to think long and hard about “Gordon Moore’s famous law,” and I drew a blank. (Here’s a link for those like me who can’t remember or don’t know what Moore’s Law is.)
Making a broad generalization such as “everyone knows x” is always dangerous. This is true in blog writing as well as in technical writing. In our style guide, we have a rule that writers should “not use simple or simply to describe a feature or step.” By labeling something as simple, it’s guaranteed you will offend someone who doesn’t understand the concept. For example, while editing one of our white papers about the DITA Open Toolkit, I saw the word “simply” and took great delight in striking through it. From where I stand, there is little that is “simple” about the toolkit, particularly when you’re talking about configuring output.
Don’t get me wrong: I’m not saying that a blog entry, white paper, or user manual about very technical subjects has to explain every little thing. You need to address the audience at the correct level, which can be a delicate balancing act with highly technical content: overexplaining can also offend the reader. For example, in a user manual, it’s probably wise to explain up front the prerequisite knowledge. Also consider offering resources where the reader can get that knowledge: that way, you get around explaining concepts but still offer assistance to readers who need it.
In the case of online content and blog entries, you can link to definitions of terms and concepts: readers who need help can click the links to get a quick refresher course on the information, and those who don’t can keep on reading. The author of the blog post in question could have inserted a link to Moore’s Law. Granted, he does define the law in the second paragraph, but he lost me with the “everyone has heard” bit at the start.
That “everyone has heard” assumption brings me back to my primary point: don’t make your readers feel stupid, particularly by making sweeping assumptions about what “everyone” knows or by labeling something as “simple.” Insulted readers move on—and may never come back.
The good manager litmus test: process change
March 10th, 2010 by Alan Pringle
For Kai Weber, a good manager is pivotal in making a job satisfying:
It’s the single most important factor in my satisfaction with a job. Nothing else shapes my memory and my judgment of a past job as much.
What really tests the mettle of a manager is how he or she handles process change. A good manager is absolutely critical when a documentation department switches to new authoring and publishing processes, particularly when moving from a desktop publishing environment to an XML-based one. Without good management, the implementation of new processes will likely fail. (I’ve seen bad management kill an implementation, and it’s ugly.)
So, what does a good manager do to ensure a smooth(er) transition? From my point of view, they will take the following actions (and this list is by no means all encompassing):
- Demonstrate the value of the change to both upper management and those in the trenches. A manager can often get the approval from upper management on a workflow change by showing cost savings in localization expenses, for example; (less) money talks to those higher up on the corporate chain. But mentions of reduced costs don’t usually warm the hearts of those who are doing the work. A good manager should show team members how the new process eliminates manual drudgery that everyone hates, explain how authors can focus more on writing good content instead of on secondary tasks (such as formatting), and so on. Demonstrating how the team’s work experience improves is more important than showing improvements in the bottom line—even though the cost savings are a result of those very changes. There is also the angle of professional development for a staff moving to a new environment; more on that in the next bullet.
- Ensure those working in the new process understand the new tools and technologies by offering training/knowledge transfer. A good manager knows that changing processes and not including some sort of training as part of the transition is foolish; knowledge transfer should be part of the project cost. Sure, not all companies can afford formal classroom training, but there are less expensive options to consider. Web-based training is very cost effective, particularly when team members are geographically dispersed. Another option is training one or two team members and then having them share their expertise with the rest of the group (“train the trainer”). The benefits of knowledge transfer are two-fold: team members can ramp up on the new processes in less time (thereby more quickly achieving the cost savings that upper management likes so much), and the team members themselves gain new skills in their profession. A good manager recognizes that training benefits both the company as a whole and individual employees (and he or she can help team members recognize how they benefit in the long term professionally from learning new skills).
- Know the difference between staff members who are bringing up legitimate issues with the new workflow and those who are being recalcitrant just to maintain the status quo. During periods of change, a manager will get pushback from staff. That’s a given. However, that pushback is a very healthy thing because it can point out deficiencies in the new process. A good manager will take feedback, consider it, and modify the process when there are weaknesses. Addressing genuine feedback in such a manner can also help a manager win “converts” to the new process. However, there may be an employee (or two) who won’t be receptive to change, regardless of how well the manager has explained the change, how much training is offered, and so on. In these cases, the manager may need to consider other assignments for that employee: for example, maintaining legacy documentation in the old system, particularly when that employee’s domain knowledge is too important to lose. There are more unpleasant options (including termination) the manager may need to consider if the recalcitrant team member isn’t providing other value to the organization as a whole. Basically, a good manager won’t let one individual poison the working environment for everyone else.
I will be the first to say that these tasks are not easy, particularly dealing with an employee who is utterly against change. But managers need to address all of the preceding issues to ensure a smooth transition and to keep the work environment positive and productive for the staff as a whole.
I won’t even pretend I have covered all the issues managers need to address when a department changes workflows, and each company will face its own particular challenges because of differences in corporate culture, and so on. If you’ve been through a workflow transition, please share your experiences in the comments: I’d love to hear from both managers and team members on what worked well (and what didn’t) in how management handled the changes.
PS: You can read a more detailed discussion about managing process change in our white paper, Managing implementation of structured authoring (HTML and PDF).
Channeling your inner Simon Cowell: help choose our next webcast topics
February 25th, 2010 by Alan Pringle
Our free webcasts have been a big success, so we’d like to offer thanks to everyone who has attended the sessions. We’re particularly grateful to those of you who have suggested topics for future webcasts.
We’ve compiled many of those suggestions into a list of topics we’re considering for future events, but we want to know which subjects really grab your interest before we make any decisions. Be part of our judges panel by filling out a brief survey that will take about two minutes of your time:
The survey will close on March 5, 2010. We appreciate your feedback.
By the way, there’s still time to register for our upcoming webcasts on DITA-FMx and XMetaL; visit our events page for more information and to register. You can also watch recordings of past webcasts in our archive.
PS: I couldn’t end this post without showing Mr. Cowell in action. I hope your reactions to our list of possible webcast topics aren’t as harsh!
Finding the blogging superhero in yourself
February 3rd, 2010 by Alan Pringle
Power blogger.
That’s a new phrase to me, and it was new to Maria Langer, too, as she noted in her An Eclectic Mind blog. As part of a podcast panel, she was asked to offer advice on how to become a power blogger. Some of her fellow panelists mentioned the quantity of posts, but Maria’s focus was elsewhere:
The number of blog posts a blogger publishes should have nothing to do with whether he’s a power blogger. Instead, it should be the influence the blogger has over his readership and beyond. What’s important is whether a blog post makes a difference in the reader’s life. Does it teach? Make the reader think? Influence his decisions? If a blogger can consistently do any of that, he’s a power blogger.
I couldn’t agree more. I appreciate reading any blog that gives me useful information or analysis that hadn’t occurred to me. For example, I recently had issues with a new PC I’m using at home as a media center. It was not picking up all the channels in my area, and an excellent blog post helped me solve the problem with little fuss. To me, that author is a power blogger.
What I frankly find irritating—and certainly not my worth my time—are blogs that are basically what I’ll call “link farms”: posting links or excerpts from other blogs with no valuable information added. I’m quite the cynic, so when I stumble upon such a blog, I figure the blogger is merely trying to generate Google hits and ad revenue, is lazy, or both. Quantity—particularly when said quantity is composed of rehashed material from other bloggers—does not a power blogger make.
When it comes to contributing to this blog, I try to write posts that have a least one nugget of helpful information, analysis, or humor, and I think that’s true of the posts from my fellow coworkers. (At the risk of sounding like I’m bragging about my coworkers, I can’t tell you how many times I’ve read one of their posts and thought, “That’s smart!” or “That’s cool!”) Frankly, I’d rather not write anything at all than to publish something just because it’s been a few days since I posted. And I have a lot more respect for bloggers who write quality posts once in a while over those who put out lots of material that is borrowed from elsewhere.
And on that note, I’ll leave you with a short clip showing superheroes using their powers for a practical solution. (See, I’m trying to entertain you, too!)
ePub + tech pub = ?
January 29th, 2010 by Alan Pringle
At Scriptorium earlier this week, we all watched live blogs of the iPad announcement. (What else would you expect from a bunch of techies?) One feature of the iPad that really got us talking (and thinking) is its support of the ePub open standard for ebooks.
ePub is basically a collection of XHTML files zipped up with some baggage files. Considering a lot of technical documentation groups create HTML output as a deliverable, it’s likely not a huge step further to create an ePub version of the content. There is a transform for DocBook to ePub; there is a similar effort underway for DITA. You can also save InDesign files to ePub.
While the paths to creating an ePub version seem pretty straightforward, does it make sense to release technical content as an ebook? I think a lot of the same reasons for releasing online content apply (less tree death, no printing costs, and interactivity, in particular), but there are other issues to consider, too: audience, how quickly ebook readers and software become widespread, how the features and benefits of the format stack up against those of PDF files and browser-based help, and so on. And there’s also the issue of actually leveraging the features of an output instead of merely doing the minimum of releasing text and images in that format. (In the PDF version of a user manual, have you ever clicked an entry in the table of contents only to discover the TOC has no links? When that happens, I assume the company that released the content was more interested in using the format to offload the printing costs on to me and less interested in using PDF as a way to make my life easier.)
The technology supporting ebooks will continue to evolve, and there likely will be a battle to see which ebook file format(s) will reign supreme. (I suspect Apple’s choice of the ePub format will raise that format’s prospects.) While the file formats get shaken out and ebooks continue to emerge as a way to disseminate content, technical communicators would be wise to determine how the format could fit into their strategies for getting information to end users.
What considerations come to your mind when evaluating the possibility of releasing your content in ePub (or other ebook) format?
Unedited content will get you deleted
January 14th, 2010 by Alan Pringle
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.
Are you ready for mobile content?
December 16th, 2009 by Alan Pringle
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.
2010: A DITA Odyssey
December 10th, 2009 by Alan Pringle
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)
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 training@scriptorium.com.
Would you use just a gardening trowel to plant a tree?
November 25th, 2009 by Alan Pringle
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
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.”
Register for our free webinar before holiday madness begins
November 18th, 2009 by Alan Pringle
Before the hectic holiday season arrives, register for Sarah O’Keefe’s upcoming free webinar:
Date: December 8, 2009
Time: 11 a.m. Eastern
Topic: Strategies for coping with user-generated content
Details and registration: https://www2.gotomeeting.com/register/583647346
Even if you don’t have holidays in the upcoming weeks, please register soon.
There is no charge to attend, but registration is required. If we get good attendance for this session, we’ll likely do more free events in 2010.
Closeout pricing on FrameMaker 7 and 8 reference books
November 9th, 2009 by Alan Pringle
We have drastically lowered the prices of our reference books on FrameMaker 7 and 8:
- The PDF download of Publishing Fundamentals: FrameMaker 7 is now $14.99. (The download was $39.99.)
- The combination of the printed book and PDF download of Publishing Fundamentals: Unstructured FrameMaker 8 is now $19.99, and the PDF download is $14.99. (The printed version’s cover price is $49.99.)
So, if you’re still in the market for books about the previous versions of FrameMaker, you can find yourself a real bargain by buying directly from Scriptorium.
PS: You can also purchase the printed FrameMaker 8 book from us through Amazon Marketplace for $19.99 (plus shipping).
Don’t forget localization
November 6th, 2009 by Alan Pringle
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.
Contest for The Compass ends Sunday: enter today!
October 22nd, 2009 by Alan Pringle
If you’d like to win a free copy of our white paper compilation, The Compass, enter the drawing by Sunday:
We’ll announce three winners on Monday.
Win a copy of The Compass
October 16th, 2009 by Alan Pringle
Our white paper compilation, The Compass (ISBN 9780970473387), is now available at online bookstores, including amazon.com, amazon.ca, amazon.co.uk, and bn.com. You can also special order a copy at your local bookstore. The cover price is $15.95 (USD), but some online sellers are offering the book at a discount.
To celebrate the release of The Compass, we’re giving away three copies.
We’ll announce the winners on October 26. Good luck!
FYI: If you plan to attend LavaCon (October 24-27 in New Orleans), you can get a free copy of The Compass from Sarah O’Keefe. She will give away a limited number of copies while she’s at the conference.
The Compass: Coming soon to bookstores and conferences
September 28th, 2009 by Alan Pringle
In October, we’re releasing a compilation of our white papers in a 160-page book, The Compass: Essential Reading about XML, DITA, and Web 2.0 (ISBN 978-0-9704733-8-7).
Over the years, thousands of technical communicators have downloaded our white papers in PDF format or have read the HTML versions. At a conference a few years ago, we distributed some papers in saddle-stitched booklets with bright yellow covers, and attendees pounced on them. We dubbed that booklet “The Little Yellow Book,” and we haven’t forgotten how popular it was.
The Compass is an expanded, perfect-bound version of The Little Yellow Book. It contains the following papers:
- Structured authoring and XML
- Managing implementation of structured authoring
- Assessing DITA as a foundation for XML implementation
- Hacking the DITA Open Toolkit
- Creating PDF files from DITA content
- Friend or foe? Web 2.0 in technical communication
We will give away a limited number of copies at upcoming conferences, including LavaCon (October 24-27). You’ll also be able to buy it from booksellers; online bookstores will likely sell it at a discount off the $15.95 (USD) list price.
You still can read the content for free at our web site; the book doesn’t contain any new or different information. The Compass just gives you the option of reading the same content in an affordable, handy book. We know there are many folks who still like to read their content in printed books (and I include myself among those people).
When we release The Compass, we’ll also have a drawing for a few copies. Watch this blog for details about the upcoming giveaway.
BTW, our very own David Kelly designed the cover, which I really like.
Font snobbery? (I don’t think so.)
September 4th, 2009 by Alan Pringle
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:
Closeout sale on second edition of Technical Writing 101: now $12.95
August 19th, 2009 by Alan Pringle
We still have a few copies left of the second edition of Technical Writing 101. I want these last copies out of the office (how’s that for truth in advertising?), so I have marked them down to $12.95. You can get free shipping within the U.S. when you purchase through our store.
We’re also offering the book for $12.95 through our Amazon.com store, but there is no free shipping there. (We’re also selling slightly damaged copies at Amazon for $10.95.)
If you prefer to get the latest edition, you can download it in PDF format for $20.
In defense of English majors: we can understand business issues, too
July 27th, 2009 by Alan Pringle
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.)
Lost in translation (and in my brain)
July 23rd, 2009 by Alan Pringle
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!
Error message melodrama
July 20th, 2009 by Alan Pringle
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.
Printed version of Technical Writing 101 now sold at infibeam.com
July 17th, 2009 by Alan Pringle
The printed version of Technical Writing 101 (third edition) is currently available at infibeam.com, which provides free shipping to cities in India. At the time of this posting, Infibeam is offering the book for 1407 rupees (24 percent off the list price).
Those who want instant access to Technical Writing 101 can download it in PDF format from our online store for $20 (USD).
Publishing Fundamentals print/PDF bundle: $24.99 for 24 hours
July 14th, 2009 by Alan Pringle
Our big sale on Publishing Fundamentals: Unstructured FrameMaker 8 starts tomorrow morning.
From 8 a.m. tomorrow until 8 a.m. Thursday (Eastern time), you can purchase the print and PDF bundle of Publishing Fundamentals: Unstructured FrameMaker 8 for just $24.99. That’s half off the list price of $49.99 (and cheaper than the cost of just the PDF download, which is $29.99).
You don’t need a coupon code to get the special price: just order within the 24-hour window.
On Wednesday, July 15: big one-day sale
July 10th, 2009 by Alan Pringle
I always laugh when department stores advertise a one-day sale and then have a “preview day” on the day before. Last time I checked, that’s a two-day sale.
Well, we’re going to have a big one-day sale on Publishing Fundamentals: Unstructured FrameMaker 8 next Wednesday, and we really mean a one-day sale. From 8 a.m. on July 15 until 8 a.m. July 16 (Eastern time), you can purchase the print and PDF bundle of Publishing Fundamentals: Unstructured FrameMaker 8 for just $24.99. That’s $25 off the list price of $49.99–and cheaper than the cost of just the PDF download, which is $29.99.
You don’t need a coupon code to get this special price on the print and PDF bundle, and you can order multiple copies, too. Just be sure to order sometime between 8 a.m. Wednesday and 8 a.m. Thursday.
Please spread the word about this sale!
Congratulations to contest winners…
July 1st, 2009 by Alan Pringle
…Bjørn Smalbro and Dave Truman, who will receive printed copies of Technical Writing 101.
Thanks to everyone who entered the drawing. Even if you didn’t win, you should have received an email with a coupon code for $5 off the PDF download of the book. (If you indicated that you teach technical writing, you should have received a code for a free review copy.)
Keith Soltys posted a review of Technical Writing 101 on his Core Dump blog yesterday. I’m pleased to report the review is positive.
A special alert to my fellow bargain hunters out there: Amazon.com is selling Technical Writing 101 at a steep discount. At the time I posted this blog entry, Amazon is offering the book for $23.73 (34 percent off the $35.95 cover price). The price does fluctuate, so who knows how long that discount will be in effect.
Enter soon: Technical Writing 101 contest ends tomorrow
June 29th, 2009 by Alan Pringle
We’re giving away two printed copies of Technical Writing 101 (third edition) on Wednesday. Please enter the drawing before it closes tomorrow.
We’re giving away the books to celebrate the book’s wider release to online bookstores such as Amazon.com, Amazon.co.uk, Amazon.de, Amazon.fr, and BN.com; you can also place a special order for Technical Writing 101 at your local bookstore. If you want instant access to the book, you can download the PDF version for $20 from our online store.
We achieved this wider distribution by working with another print on demand (POD) company, Lightning Source. We’re quite happy with the quality of the books from our other POD partner, Lulu.com. However, at this time, Lulu doesn’t offer distribution for publishers who use their own International Standard Book Numbers (ISBNs). We’ve released books under our own ISBNs since we published the first edition of Technical Writing 101 in 2000, and I frankly was not comfortable assigning an ISBN owned by a POD firm to content we developed. Using a publisher’s ISBN would cause problems if we wanted to switch to another publisher later. We’d have to assign a new ISBN, and then the book would be in the marketplace with two different ISBNs. I wanted to prevent that marketing (and distribution) headache from ever happening.
I’m not going to write a long post about the virtues of Lulu.com and other POD publishers vs. Lightning Source because many other people have done that (in this blog post, for example). What I will say, though, is that Lightning Source is geared more toward experienced publishers, and Lulu provides more guidance that newer authors and publishers will certainly appreciate. If you want to get your feet wet in the POD pool, Lulu is a great place to start, but if you’re a publisher who has published several titles with your own ISBNs, Lightning Source may be better suited for your needs.
Win a printed copy of Technical Writing 101 (third edition)
June 24th, 2009 by Alan Pringle
As of this week, the printed version of Technical Writing 101 (ISBN 9780970473363) is available at online bookstores, and you can also special order a copy from your local bookstore. To celebrate the book’s wider distribution, we’re giving away two printed copies.
Enter the contest by June 30 (next Tuesday). We’ll pick two winners at random on July 1.
The printed book is now listed at many online stores, including Amazon.com, Amazon.co.uk, Amazon.de, Amazon.fr, and BN.com. (FYI to all you bargain hunters out there: some of these stores are selling the book at a discount and with free shipping, too.)
For those of you who want instant (and cheaper) access to the book, we’re still offering the PDF download (ISBN 9780970473370) for $20. The download (which has been particularly popular with buyers outside the US) is available only through our online store.
Later, I’ll write more about how we achieved the wider distribution of the printed version through our new print-on-demand partner, Lightning Source, and how Lightning Source compares to Lulu.com.
Our first experience with print on demand (POD)
June 3rd, 2009 by Alan Pringle
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.
Technical writing and social networks
June 1st, 2009 by Alan Pringle
There is an interesting thread on techwr-l about using social networking sites to deliver product information. In the thread, Geoff Hart notes there is a generation gap in those who turn to unofficial online resources vs. product documentation:
The young’uns go to the net and social networks more than we older folk, who still rely on developer-provided documentation. We ignore this change at our peril. Cheryl Lockett Zubak had a lovely anecdote at WritersUA a few years ago about how she and her son both set out to solve an iPod problem; they both found the solution in roughly equal amounts of time, but she found it in Apple’s documentation, while her son found it on YouTube.
My experience as a user straddles both relying on official docs and information available elsewhere. When my iPod locked up a few years ago, I found decent information on Apple’s web site, but the best resource for my particular problem turned out to be on YouTube. A user had made a video showing step-by-step what to do.
The dilemma of official docs vs. Web 2.0 information partially boils down to question of audience. As part of the process for planning and developing content, technical communicators should evaluate and remember the audience, and that audience consideration now needs to extend to how a company distributes the content. I don’t think there are cut-and-dried answers here; for example, it’s unwise to make the assumption that all folk over a certain age are unaware of or don’t use social networks and other Web 2.0 resources. Ignoring unofficial information channels is certainly not the solution, however.
This weekend, get $5 off printed copies of Technical Writing 101
May 21st, 2009 by Alan Pringle
Starting tomorrow through Monday, you can get $5 off a printed copy of Technical Writing 101, which is normally $35.95. To get the discount, use the code MEMORIAL09 during checkout at Lulu.com.
Here is Lulu’s fine print on the coupon code:
Offer valid on orders placed within the United States only. Enter code ‘MEMORIAL09’ during checkout and save $5.00 off any purchase of $25.00 or more. Discount cannot be used to pay for, nor shall be applied to, applicable taxes or shipping and handling charges. Promotional codes cannot be applied to any previous orders. No exchanges or substitutions allowed. Only one valid promotional code may be used per account. Offer valid from 05/22/09 through 05/25/09 at 11:59 PM GMT. Lulu.com reserves the right to change or revoke this offer at any time. Void where prohibited. Please note that coupon code is case-sensitive.
Get 10 percent off a printed copy of Technical Writing 101
May 15th, 2009 by Alan Pringle
If you have been waiting for a discount to purchase a printed copy of the third edition of Technical Writing 101, now is your chance. Through May 31, 2009, use the code MAYCONTEST10 during checkout to get 10 percent off when buying a printed copy from Lulu.com. The printed version is $35.95 (before the discount). FYI: the discount isn’t applied to shipping or taxes.
Technical Writing 101 is also available as a $20 download from our online store (but the Lulu discount doesn’t work there).
By the way, if you received a coupon code for entering our contest, use that code now! The discount code expires today.
Technical Writing 101 contest: and the winners are…
May 8th, 2009 by Alan Pringle
Congratulations to Ravindra Kumar, Judy Walters, and Axel Regnet, who each won a free download of Technical Writing 101. As a thank-you to entrants who didn’t win a free copy, we offered a $5 discount off the $20 price.
All entrants should have received an email with a coupon code for a free download or $5 off. We appreciate your interest in our books.
Enter today: Technical Writing 101 giveaway ends tomorrow
May 6th, 2009 by Alan Pringle
We are closing our drawing for free downloads of Technical Writing 101 tomorrow. If you haven’t already entered the contest, enter today. We’ll pick three winners and notify them via email on Friday.
If you want to sneak a peek at what’s in the new edition, you can read the table of contents and excerpts from two chapters (PDF), and you can see the preview provided by Google Book Search. (Be forewarned that some pages in the Google preview weren’t processed cleanly, but they are still readable.)
Technical Writing 101 is now available. Win a free download!
April 29th, 2009 by Alan Pringle
Technical Writing 101 (third edition) is now available for purchase! You can instantly download the PDF version from our online store for $20, or you can order a printed copy from Lulu.com for $35.95. We’re also offering a site license for $250: you can download the PDF version and distribute it up to 20 people.
To celebrate the book’s release, we’re giving away three downloads of the book. Enter the drawing by May 7. We’ll notify the winners via email.
Enter the drawing today!
If you’re an instructor and would like to review the book for your classes, contact us at books@scriptorium.com. In your message, tell us about the courses for which you’re considering the book and how many students attend those classes each year.
Technical Writing 101: new edition, new approach
April 22nd, 2009 by Alan Pringle
In early May, we will release the third edition of Technical Writing 101: A Real-World Guide to Planning and Writing Technical Content. We published the second edition in 2003, so it was time for an update. A lot has changed in technical communication since then!
You may have noticed a change in the book’s subtitle: the previous editions’ subtitles mention “Writing Technical Documentation,” but the new edition focuses on “Writing Technical Content.” We made that change because “documentation” conjures thoughts of printed manuals, which are no longer the primary form of output for many companies (or the new edition of Technical Writing 101, but more on that later). Because a lot of product information is now online, we added information about multimedia content to the chapter on visual communication, and we also revised the chapter on production editing to include information about reviewing online output.
Today’s tech writers are handling more and more aspects of the technical publishing process; fewer companies employ full-time editors and production staff. The new edition—which is 44 pages longer than its predecessor—accounts for this shift in roles. Other big changes in the third edition include new content about DITA and Web 2.0. DITA’s use has grown exponentially since we released the second edition, so it was essential for us to introduce DITA to prospective technical writers. The use of blogs, forums, and wikis has also had a profound influence on technical communication in the past few years, so we added a chapter that explains the impact of Web 2.0 technologies on technical writing. For more information about what’s in the new edition, check out the table of contents (PDF, 135 KB).
Perhaps the biggest change for this edition isn’t in the content: for the first time, we are releasing this title in PDF format. For $20, you will be able to download the new edition instantly from our online store. As with our other PDF-based books, the file will have no digital rights management (DRM) restrictions that prevent printing or that lock the file to a particular computer. Those who prefer a printed book can buy one in the near future from Lulu.com, which prints books on demand. A printed copy will be $35.95: the same cost as the second edition, despite the increased page count.
This is our first foray into print-on-demand books. After some number-crunching, we decided we did not want to print copies in advance and distribute them ourselves for this edition. Distributing your own printed book entails a lot of money and work: pay a printer to print and ship cases of books to you, store those cases of books, ship copies all over the world, deal with bulk returns from bookstores, and so on. We have seen a decline in the revenue from printed books (as have other publishers), so we thought it was time to try digital downloads as the primary method of selling the new edition of Technical Writing 101.
Many schools have adopted the book as a textbook since we released the first edition in 2000, and we hope the $20 price for the digital version will make it even more accessible to students—and to anyone who is considering a career in technical writing.
If you’re an instructor and would like to review the latest edition, please contact us at books@scriptorium.com. We’ll send you a coupon code so you can download the PDF version at no cost from our online store.
Watch this blog and our newsletter, Illuminations, for more details about the upcoming release.
DITA isn’t magic
February 25th, 2009 by Alan Pringle
The WritePoint staff blog makes a very good point about DITA: it isn’t a magic wand that fixes documentation problems. Also, it’s worth noting that:
… DITA didn’t introduce something completely new. DITA incorporates achievements made in a wide variety of approaches to organizing content that were being proactively conducted starting from 1960’s.
Don’t get me wrong: DITA can be a good solution for many departments that want to set up an XML-based single-sourcing environment. Just don’t expect that a twitch of your nose will convert your legacy content or make the output from the Open Toolkit match your formatting requirements.
Get $10 off two Scriptorium Press titles
February 16th, 2009 by Alan Pringle
We have just lowered prices on two books in our online store:
- Publishing Fundamentals: Unstructured FrameMaker 8: Get both the printed book and downloadable PDF file for $39.99: that’s $10 off the cover price of $49.99. (You can still download just the PDF version for $29.99.)
- Technical Writing 101 (second edition): Get the printed book for $25.95, which is $10 off the cover price of $35.95.
These discounts are available only through our online store. Please spread the word!
P.S. We’re also offering discounts on these titles through our listings on Amazon Marketplace:
Take our survey on structured authoring–and get a free report on the results
January 29th, 2009 by Alan Pringle
Curious about other folks’ experiences with considering, planning, and implementing a structured authoring/XML environment? Well, now is your chance to get that information by participating in our survey on structured authoring.
We want input from everyone: those who have implemented structured authoring, are planning to implement it, or have decided against it. The short survey will take no more than 10 minutes of your time. The deadline for responses is March 1, 2009.
In April, we will release our analysis of the results. If you participate in the survey and provide your contact information (which is entirely optional), we will give you a free copy of the report, which will cost $200. We are also going to give a $50 amazon.com gift certificate to two randomly selected people who provide contact information. (By the way, if you provide your contact information, we will not share that information with any other company.)
Take the survey today. We appreciate your help.
Personality types and tech writing
January 26th, 2009 by Alan Pringle
I’ve taken the Myers-Briggs Type Indicator (MBTI) test twice in my life: in high school and as part of a team-building exercise for my job in the mid-1990s. Both times, my results were the same–and uncannily accurate.
I’m very certain my personality type (ISTJ, which should come as no surprise to anyone who knows me) has had an impact on my job as a technical communicator and a manager. Craig Haiss over at HelpScribe has an analysis of how some personality types fit in the tech writing world.
By nature, I’m a pretty skeptical person, but I do think the MBTI can be a useful tool to figure out how your contributions can best fit within an organization. It can also help you understand what aspects of your personality may not work so well in particular situations. (I will spare you details on which aspects of my personality require my attention, but I can assure you I know what they are!)
Murder by metaphor
January 5th, 2009 by Alan Pringle
The Shanghai Tech Writer blog has a hilarious list of awful metaphors written by high school students. These gems include:
- Her face was a perfect oval, like a circle that had its two sides gently compressed by a Thigh Master.
- Long separated by cruel fate, the star-crossed lovers raced across the grassy field toward each other like two freight trains, one having left Cleveland at 6:36 p.m. traveling at 55 mph, the other from Topeka at 4:19 p.m. at a speed of 35 mph.
- They lived in a typical suburban neighborhood with picket fences that resembled Nancy Kerrigan’s teeth.
The list does provide quite a bit of entertainment (well, maybe I’m easily amused), but many of the metaphors also demonstrate why technical writers should avoid using them. Metaphors are often culturally specific and therefore difficult to translate. For example, I wonder how many folks outside of the US know what a Thighmaster is?
Our holiday schedule
December 23rd, 2008 by Alan Pringle
For the holidays, Scriptorium will be closed on December 24 and 25, and some of us will be out of the office until January 5.
Even though a few of us won’t be here for the rest of 2008 (and a bit of 2009!), you can still immediately download the PDF versions of workbooks, books, and white papers from our online store. (Printed versions purchased through January 4 likely won’t ship until January 5.)
Everyone here wishes you the best for holiday season. That includes my dog, Keely:
(Picture is courtesy of Camp Canine.)
Crosswords for technical writers
December 22nd, 2008 by Alan Pringle
If you’re looking to tease your brain during this holiday week, consider doing a crossword puzzle with a technical writing theme at the Crosswords blog. Never thought I’d see a puzzle with the clue “a family of transformational languages used to describe how to format XML files.” I love the clue for 29 across: “to wield the red pen.” That phrase should probably be the title of my autobiography. (My coworkers at Scriptorium can attest to that.)
The blog also has another tech writing puzzle and the answer keys for both.
Put the drawing tools down!
December 11th, 2008 by Alan Pringle
This list of technical writing myths has a decidedly DITA slant; I don’t necessarily like the idea of DITA driving what is and isn’t acceptable practice for technical writing. That being said, I endorse the information provided about myth #4:
4. The Callouts on Graphics Myth
If you want to reuse the same graphic in multiple publications and even multiple languages, it is a good practice not to put callouts in the source file of the graphic itself. Instead, you place your callouts “on top of” your graphic in your text editor (Word) or DTP program (InDesign, FrameMaker, …). This is not supported in DITA. Therefore, if you need to use callouts in graphics, try to use language-independent ones (A, B, C…) in the source file of the graphic and put the explanation of these callouts in a table below the graphic in your DITA XML content. [Yves Barbion]
It’s not just the DITA standard that doesn’t support callouts placed with a document processor’s drawing tools. We have a client for whom we created a custom XML structure for FrameMaker content, and that content contains many graphics with callouts. The client translates the content into multiple languages.
In the previous workflow in unstructured FrameMaker, the client placed the callouts in the anchored frame with FrameMaker’s drawing tools. However, if you do that in a structured FrameMaker workflow and save content out to XML, FrameMaker by default saves each image with added callouts into a new CGM graphic file that no longer has editable callouts. There can’t be complete round-tripping between XML and FrameMaker because the graphics aren’t preserved in this scenario.
Therefore, the rule for this client is that an anchored frame can contain just one image file imported by reference. Period. No other text, text frames, or anything. If callouts are necessary, they are included as part of the source graphic; the client adds numbered callouts in Illustrator. A numbered list specifically for explaining those callouts follows the graphic.
The XML generated from FrameMaker points to the image files, and FrameMaker doesn’t need to generate new graphic files to include any callouts added with FrameMaker’s drawing tools. (If the directory containing XML files includes a CGM file that FrameMaker created during export, that usually means there is an anchored frame somewhere that contains something more than just a referenced image file.) Another huge plus: because the callout explanations are part of the text, they are translated without changing the original graphic.
Separating callouts from your images and making them part of the text is smart for any workflow because of localization issues, and it pretty much becomes mandatory when you’re establishing an efficient structured authoring environment (and not just those based on DITA).
P.S. One other thing to think about with graphics in structured authoring environments: if you use XSL to transform your XML into online formats, determine if web-ready graphics (such as PNG files) will work in your print/PDF and online content. If so, you eliminate the need to convert images to formats for online viewing.
Some help with ditaval files and renegade attribute values
December 4th, 2008 by Alan Pringle
Over at his Core Dump blog, Keith Soltys introduced me to the Ditaval File Generation Utility by Suite Solutions. The free utility (which is for Windows only) scans the files in a ditamap and lists values for the product, platform, audience, and otherprops attributes. You can check the list to be sure the values are right and then generate a ditaval file.
I haven’t used this tool yet myself, but I can think back to a project where it would have been very helpful in tracking down just a few incorrect attribute values lurking in hundreds of DITA topic files. At the time, I used TextPad to search on all the files within directories, but I could only search on one attribute name (or flaky value) at a time. If this utility works as advertised, it would eliminate that problem.
We’ve been localised
November 21st, 2008 by Alan Pringle
Over the years, I have worked on manuals that were translated, and I have helped clients with their localization processes. Despite those experiences, I’ve never been part of a project in which US English was localized (well, localised) into UK English–until now.
Cherryleaf has adapted material from our Technical Writing 101 book in its new Basics of Technical Authoring self-paced course. Cherryleaf is based in the UK, so the course is tailored for those accustomed to British English, but the content is helpful to any English speaker who wants to learn the basics of technical writing. Cherryleaf has also included exercises so students can get some experience applying the techniques explained in the course content.
(Full disclosure: Scriptorium is compensated for sales of Cherryleaf’s course.)
Writing from the past: the Dead Sea Scrolls
October 27th, 2008 by Alan Pringle
I visited an exhibit showing some of the Dead Sea Scrolls yesterday. The ancient texts were indeed the star attraction, but there were two bits of information I found particularly interesting:
- During the excavation of Qumran (a settlement near the caves where the scrolls were discovered), inkwells were found in a room with the remains of bench-type furniture. Some believe that the room was a scriptorium where manuscripts were copied. Even though the bench could have been used much like the desks we use today, some scholars believe that such use didn’t occur until medieval times. The people using the bench may have sat on the floor with their backs to the bench. The exhibit had a reproduction of the bench and drawings of how it may have been used. (By the way, some scholars do not interpret the room as a scriptorium but as a dining room instead.)
- Those attempting to restore the works in the 1950s meant well, but the techniques they used were damaging. People handled the fragments with bare hands, smoked while working with the fragments (!), and used cellophane tape to put fragments together. Restoration efforts of today include removing the adhesive residue left by the tape.
A technical writing ditty
October 23rd, 2008 by Alan Pringle
I’m constantly amazed by what you can find on YouTube, and this clip from a clever tech writer is no exception:
The Golden Rule of technical writing
October 6th, 2008 by Alan Pringle
I stumbled upon a list of tips for technical writers, and I was glad to see tip 7:
Understand Your Target Audience. Write and revise your content according to how your target audience thinks and understands things. Getting into their heads–knowing how their minds process information, how they might react, what they feel is important–allows you to customize your content to tailor-fit their needs.
I would put that tip at the top of the list, but that’s a quibble.
Sarah and I mention the topic of audience a lot in our Technical Writing 101 book; I think it is the most important thing for writers to remember as they create content. You can have an elegant XML-based publishing system that generates all sorts of output with the push of a button, but if your information doesn’t address the needs of users, all the work put into the content and into the process itself is wasted.
That waste becomes even more acutely painful when a user abandons your information and finds helpful content on a blog, wiki, or forum. The contributors of that information probably don’t know (or even care) that they followed the Golden Rule of technical documentation: Audience, audience, audience.
DITA OT installation: check your JDK version if you’re having problems
September 30th, 2008 by Alan Pringle
I have been indulging in a bit of avoidance behavior by not installing the DITA Open Toolkit on my newer laptop. Well, I broke down today and installed the latest build of the OT, but the experience was not pain free, for sure. (And it was equally not fun when I installed it on my previous computer.)
To make a long story short, I had an older version of the JDK that was causing my first test run to barf while creating XHTML output, and searching on the error messages led to a helpful blog entry:
OK, so I download and install JDK 1.4.2.18, set my JAVA_HOME environment variable, and add the location of the Java executable to my CLASSPATH environment. I restart my system for good measure, run startcmd.bat, and try to run some of the samples. The build fails, with a “java.lang.UnsupportedClassVersionError: org/dita/dost/invoker/AntInvoker (Unsupported major.minor version 49.0)” message. Arggh.
I surf over the dita-users group on Yahoo! and try to search the archives, but the search mechanism is temporarily broken. When I eventually search my e-mail locally, I find a thread that lets me know that JDK 1.5.x is required. Once this JDK is installed, the samples run as they should. I know enough Ant to quickly add a few targets to the build_demo.xml and generate the CHM and PDF files that I wanted.I installed the latest JDK and set the JAVA_HOME environment variable, and all was well after that.
I looked back at the installation documentation that’s included in OT download, and it does indeed mention an old (and incorrect) version of the JDK:
- Java runtime or development environment
- Provides the basic environment for most tools used in this toolkit.
You can download and install the Java Development Kit (JDK) 1.4.2 (available on http://java.sun.com/j2se/index.jsp) into a directory of your choice.
The online version of the OT documentation has the correct JDK requirements:
DITA Open Toolkit is written in Java and requires at least a minimal set of Java applications be installed. Java SDK 1.5 or 1.6 must be used to execute the applications and the Toolkit Java code.
So, if your new installation of the DITA OT is failing, there is a good chance you need to update your JDK.
Structure: resistance is futile (and a waste of time, really)
September 23rd, 2008 by Alan Pringle
It’s been our experience that there are always a few writers in a technical writing department who will resist adapting to a new structured authoring workflow. Apparently, that sort of behavior is not limited to writers:
It is common among both developers and technical writers who work with xml to look on schemas (the XSD files) as a necessary evil. Something they grudgingly have to accept because it’s been directed from high, but not something they would use if they didn’t have to. They do their coding, or their writing, first, and then try to force it to fit the schema.
…
You might think it strange that I am picking on developers in a technical writing blog, but let me tell you, a lot of tech writers have the same attitude. The same people who happily accept that a style manual is necessary, and that a document template is compulsory, consider the schema a nuisance—something that makes their job harder, restricts their freedom and adds extra work.
It’s nice to see this topic addressed so directly and succinctly. Yes, the learning curve for working in a structured environment can be a bit of challenge, particularly if you’ve been writing in a template-based workflow for a long time. Also, there are some cases of poorly planned and implemented structures: if many authors are struggling with a structure, that may indicate there is a problem with the hierarchy itself. Beyond that, however, it is much harder to justify (or understand) the behavior of authors or developers who resist following an established structure, even though it’s there to make work easier.
Free books are gone
August 19th, 2008 by Alan Pringle
We’ve given away all the copies of the Technical Writing 101 book. Thanks for all the responses.
We are happy the books are going to readers instead of the recycling facility!
Yet more free copies of Technical Writing 101 (first edition)
August 19th, 2008 by Alan Pringle
As I mentioned in an update to my post yesterday, we located more copies of the first edition of Technical Writing 101. We have divided this lot into four batches, each of which has nine or ten books. If you’d like one of these batches, please contact me at books@scriptorium.com. We will ship the books to you at no charge.
Update: We have given all the books away. Thanks for your quick responses!
Free copies of Technical Writing 101 (first edition)
August 18th, 2008 by Alan Pringle
We have 27 copies of the first edition of our Technical Writing 101 book. We are no longer selling that edition, so we are giving away our remaining inventory.
To keep things simple, we have divided the books into three batches, each of which has nine books. If you’d like one of these batches, please contact me at books@scriptorium.com. We will ship the nine books to you at no charge.
Update: We have shipped all three batches. However, we think there are more copies lurking about. Stay tuned…
Is this the kind of advice we should give new tech writers?
August 7th, 2008 by Alan Pringle
A recent blog post on getting that first job as a technical writer focuses quite a bit on desktop publishing tasks:
For example, I always had an aptitude for graphics, page layout, font selection, and spatial organization. I always had fun playing around with different imaging programs like Photoshop and Illustrator, or page layout programs like PageMaker.
Yet I never thought about those skills within the framework of technical writing. Back then I wasn’t even aware that more than half of the time spent on a typical technical writing project does not involve actual writing but organizing and formatting information in two-dimensional work-space.
I do not dispute having skills in different layout and illustration programs is a plus for a new tech writer. However, “organizing and formatting information” doesn’t (and shouldn’t!) take more than half of a project’s time, particularly in today’s smaller documentation departments with limited resources and tight budgets.
Taking time to figure out organization is essential, but spending a lot of time on formatting is a luxury and often unnecessary–especially in structured authoring workflows in which authors handle few (if any) formatting tasks. Even if you’re working in an unstructured environment, a good template can automate formatting tasks so you can focus on getting the content right (which is a lot more important than getting it pretty, IMHO).
The blog post also doesn’t take into account that a lot of content is single sourced these days: print, PDF, and many flavors of online help come from one set of files. Good tools can automate almost every aspect of the conversion processes for the various outputs, so there is no need to spend time formatting content.
In summary: having skills in all sorts of layout programs and illustration packages is helpful for a new tech writer. Having a basic understanding of how structured authoring solutions (including DITA) work is just as important–or even more so–for the next crop of technical writers. The days of desktop publishing for just print documentation are in the past.
No more DRaMa: DRM-free books
June 25th, 2008 by Alan Pringle
O’Reilly has announced it will start selling some titles as ebook bundles free of digital rights management (DRM) in July. I’m sure a lot discussion went into that decision because we have grappled with this very issue for our Scriptorium Press titles.
When we decided to release our FrameMaker workbooks in PDF format in February 2006, we opted not to use DRM restrictions that prevent printing or that lock the file to a particular computer. It was not an easy decision to make. We don’t want our materials to be pirated, but at the same time, we don’t want to implement DRM that can make life difficult for legitimate users. (What if you get a new laptop and your PDF file is locked down to your old one?) We also did a survey a few months ago on digital books, and folks made it very clear they would avoid files with DRM.
With the recent release of our Publishing Fundamentals: Unstructured FrameMaker 8, we took our sales of digital books even further. For the first time, we are offering buyers the option of purchasing a new reference book as a PDF file; previously, we offered digital versions for older reference books that we no longer printed. Another change with this latest release is that buyers who get the printed version also get the PDF version free. As is the case with our other digital versions, the PDF file of Publishing Fundamentals: Unstructured FrameMaker 8 is free of the DRM restrictions I mentioned earlier.
Releasing our content without any DRM may seem foolish to some. (“You’re too trusting!” “You’re inviting people to steal your stuff!”) That being said, DRM can be a huge hassle for people who actually paid for the material, and it also can be cracked. Those are two big reasons we have opted not to use it.
Printed version of Publishing Fundamentals: Unstructured FrameMaker 8 now shipping
June 20th, 2008 by Alan Pringle
A delivery person is stacking boxes of Publishing Fundamentals: Unstructured FrameMaker 8 in our back room as I type this. If you’ve ordered the printed version, your shipment will go out today or tomorrow.
Typos are the bane (and the reality) of my existence
June 19th, 2008 by Alan Pringle
A few weeks ago at the STC conference, we were distributing printed copies of our latest white paper, Friend or Foe? Web 2.0 in Technical Communication. We had some really good feedback from attendees; one person made a point of coming by the booth a second time to tell us she had enjoyed reading the paper.
Another reader with whom I had a lengthy discussion also returned to let us know that she had spotted a typo. Sure enough, she was right. I am very grateful she spoke up and told me about it. I posted a corrected version on the white papers page.
As much as I would like our books, white papers, solution briefs, and other content to be error free, the reality is that errors do slip by sometimes. That being said, we do strive to put out quality material that is clear, concise, and almost completely free of typos.
Publishing Fundamentals: Unstructured FrameMaker 8 is now available
May 30th, 2008 by Alan Pringle
As of a few minutes ago, you can buy our latest book, Publishing Fundamentals: Unstructured FrameMaker 8 from our online store.
You can purchase the printed book and PDF file combination for $49.99, or you can buy just the PDF file for $29.99. You get instant access to the PDF file–available exclusively through our online store–with either option. (Printed books will be shipped in the middle of June.)
On Sunday, I’m off to the STC conference with Matt and Sarah. Hope to see some of you there.
FrameMaker 8: The Case of the Missing S
April 24th, 2008 by Alan Pringle
I have been reviewing the content in Publishing Fundamentals: Unstructured FrameMaker 8, which we plan to release next month. While reviewing the chapters, I have been reminded about some FrameMaker features I had forgotten, but I’ve also discovered a few puzzling things in the interface of version 8.
For example, there is a toolbar for the new feature that tracks text edits. To see the toolbar, select View > Track Text Edit Bar. The Track Text Edits toolbar is displayed. If the toolbar has Edits in its name, why does the View menu choice show just Edit?
I think this is a case for The Hardy Boys and Nancy Drew. I bet they could track down that missing s.
When not-so-related links attack
March 19th, 2008 by Alan Pringle
In his presentation today, Michael Hughes mentioned that writers sometimes get a little too link-happy in help. For example, we may think we’re being helpful by providing a link to a topic that we see as related in the grand scheme of things. However, to a user who is focusing on a particular task that has no immediate dependency on a “related” topic, that link is unnecessary or even a distraction.
Michael’s objective was to create topics that give the writer just enough information to get back on track without interrupting the task flow. Providing lots of links can get in the way of the flow. That being said, it’s probably unwise to take this more minimalist approach as a license not to put in links at all. For example, links that define terms or acronyms can be crucial to understanding a task.
Things I’ve learned at WritersUA that have nothing to do with technical communication
March 19th, 2008 by Alan Pringle
I’ve been in Portland with Sarah and Matt at the WritersUA conference. I’ve attended some informative sessions, but I have also picked up a few bits of information that I didn’t learn from a conference presenter:
- There is good food in Portland. Some friends who live in Oregon met me in Portland, and they took me to a restaurant that’s quite a bit off the beaten path. Lovely Hula Hands resides in a cozy old house, and the food we ate was excellent. The caramel and amaretto custard earned high marks from all of us; a friend referred to it as “camaretto.”
- Having a stain-resistant finish on your pants can be helpful when you’re bleeding. I sat down in one session and noticed red streaks on my tan wool pants. I thought I might have brushed up against a table or box around our booth and gotten something on my pants, but then I saw blood on a finger. I had unknowingly cut my hand and transferred the blood to my pants leg. I thought I had ruined the pants, but I was able to get the stains off easily by dabbing at them with a paper napkin and a bit of water from the bottle I was toting around. I had no idea the pants were stain resistant, so that was a happy bonus for the day.
- Going to a hands-on session 20 minutes ahead of time is still not enough time to install software and files. Yesterday, I attended Rob Houser‘s double session on using Captivate. Sarah recommended I get down there early to get the software and files installed, and I did just that. My laptop, however, was highly uncooperative. (Why yes, it does have Vista on it!) It refused to read the memory stick that had the exercise files, and the installation process for the software itself got stuck in some sort of loop. About 25 minutes into the session, it was clear I wasn’t going to be able to complete the exercises. I ran a System Restore on my laptop while watching the presentation. BTW, my hat is off to Rob Houser. It takes a very brave soul to run a hands-on presentation. All sorts of challenges can arise: computer issues (just like mine), differences in attendees’ experience, and so on. He handled a tough situation quite well.
Good advice for system admins and technical writers
March 14th, 2008 by Alan Pringle
A recent article offers tips for system administrators to be competitive in today’s job market. A lot of the suggestions apply to those in the technical writing field, too.
The following point is worth repeating because I have forgotten it myself in the heat of deadlines:
Customer service skills. A system administrator (or system admin) constantly interacts with people, responding to their problems (and resolving them), and attempting to keep the customer happy. Make no mistake — these are your customers, even if they are in the same company.
Substitute “tech writer” for “system admin” and “end user” for “customer” in the example, and you have a very useful piece of advice. Interacting with end users–internal or external–is essential to ensure that documentation is as useful as it can be.
Because of tight schedules and resource problems, I think it’s really easy to get into a bunker mentality and basically shut down contact with the outside world to crank out deliverables. Unfortunately, that’s among the worst things you can do: isolating yourself from useful feedback just perpetuates problems in documentation, many of which you may not have anticipated because you are too familiar with the product.
Companies are beginning to use Web 2.0 technologies in their documentation processes, though, and that enables instant feedback from users. (BTW, Sarah is presenting on this very topic at the WritersUA conference in Portland, Oregon, next week. I’ll be there, too.)
All this being said, sometimes your external customer (the end user) wants something different than your internal customer (your management). Balancing these competing requirements can be difficult, to say the least.