Robert Desprez Communications

MARRYING TWITTER WITH USER DOCUMENTATION

by 11 Comments

I just got back from the Writ­er­sUA tech­ni­cal writ­ing con­fer­ence yes­ter­day in Long Beach, Cal­i­for­nia. As I expect­ed, I attend­ed many real­ly inter­est­ing sessions.

Here’s one great idea. Sarah Mad­dox, an Aus­tralian tech­ni­cal writer, works at Atlass­ian, the com­pa­ny that devel­ops JIRA (bug and issue track­ing soft­ware) and Con­flu­ence (web-based cor­po­rate wiki soft­ware). She and her team cre­at­ed wiki doc­u­men­ta­tion that com­bines tra­di­tion­al tech­ni­cal doc­u­men­ta­tion, social media, and links to relat­ed blog posts. Here’s a screen capture:

 

This screen cap­ture shows a sam­ple of Atlassian’s wiki doc­u­men­ta­tion, which includes a Twit­ter stream at the bot­tom of the page.

If users tweet on a giv­en top­ic, they’re reward­ed by giv­en an online badge that they can add to their own blogs or social sites.

Sarah and her col­leagues at Atlass­ian have pulled off a rare feat—content that mar­ries tech­ni­cal doc­u­men­ta­tion, social media, and even viral mar­ket­ing. Because users who decide to tweet are offered an online badge, oth­ers might see the badge on anoth­er site and then tweet as well, which could lead to more and more users con­tribut­ing to the dia­log via Twitter.

This project won the most inno­v­a­tive idea at the Writ­er­sUA “peer show­case.” I think it’s a great idea and well deserved.

INSPIRING VIDEO OF WIRED MAGAZINE RUNNING ON AN iPAD

by 1 Comment

When Apple unveiled the new iPad yes­ter­day, it remind­ed me of this very cool video—a demo of an elec­tron­ic ver­sion of Wired mag­a­zine that has been opti­mized for use on the device that every­one seems to want. Imag­ine if users could read­i­ly inter­act with elec­tron­ic user guides or help sys­tems this way? Inspiring.

http://www.youtube.com/watch?feature=player_embedded&v=wwFbwHaP5tE

MAKING ONLINE HELP SEO FRIENDLY

by 3 Comments

When you’re look­ing for help when faced with some tech­nol­o­gy-relat­ed ques­tion, how do you find assistance?

Maybe you ask a per­son if you’re at work. Per­haps you fire up the help with the prod­uct, if it’s avail­able. Maybe you vis­it the company’s web site and troll through the sup­port sec­tion, look­ing for the answer to your ques­tion. But increas­ing­ly, I sus­pect that more and more users are typ­ing the prob­lem they face into Google’s search field because more often than not, it pro­vides the most accu­rate and rel­e­vant results.

As a tech­ni­cal writer, if you’re post­ing con­tent online that can be searched by search engines, it may be worth bor­row­ing Search Engine Opti­miza­tion (SEO) tac­tics to make your con­tent easy to find on the Inter­net. Some back­ground: SEO is the process of improv­ing the vis­i­bil­i­ty of a web site using search results. So, for exam­ple, if you work as a tech­ni­cal writer in Seat­tle and some­one types the key­words “Seat­tle tech­ni­cal writer” into Google, ide­al­ly your web site is one of the first to dis­play in the results.

Now imag­ine that you gen­er­ate Web­Help for your com­pa­ny and it’s host­ed on a web serv­er that can be searched by Google. As some­one who has per­formed SEO and web ana­lyt­ics on a web site, here’s how I’d start to make the help “SEO friend­ly” so that it appears promi­nent­ly in the search results.

(NOTE: This top­ic pro­vides just an overview of “organ­ic” SEO tac­tics. The oth­er main way to improve your search results is by pay­ing for them but I won’t deal with this method in this blog entry.)

  1. Dou­ble-check that the <title> tag of your online help is an accu­rate descrip­tion. I’d include three ele­ments of the title tag: com­pa­ny name, prod­uct name, and the phrase, “Online Help.” For exam­ple, “ACME RasterBlaster Online Help.” Ensur­ing the title tag is clear is one key way to help with SEO rankings.
  2. Add lots of relat­ed hyper­links that point to the help. Make sure that rel­e­vant web sites (for exam­ple, your sup­port web site, forums on the prod­uct, relat­ed blogs) have links point­ing to your help, which improve SEO rank­ings. Aim for qual­i­ty links, not quantity.
  3. Ana­lyze key­words. Key­words are the terms that your users type when search­ing for help on your prod­uct, such as “con­fig­ur­ing RasterBlaster.” When you know these key­words, make sure that you’ve lib­er­al­ly added the same terms to your “Con­fig­ur­ing RasterBlaster” help top­ic. Adding key­words to your con­tent is anoth­er key way to improve SEO results. Google AdWords is one tool that helps with ana­lyz­ing key­words on a web site.
  4. Add meta-data to impor­tant top­ics in the help. In the <meta> tag in the HTML code for an impor­tant help top­ic, make sure you add rel­e­vant syn­onyms that ide­al­ly match the key­words a user might type in a search engine.
  5. After you’ve per­formed some of the pre­vi­ous sug­ges­tions, be patient. Results don’t hap­pen overnight. After 10 days, type the iden­ti­fied key­words (for exam­ple, ACME RasterBlaster Online Help) into Google. Where are you locat­ed in the results? If you’re not ranked very well, per­haps you need to tweak your key­words, meta-data, or point more rel­e­vant links to the help sys­tem. In anoth­er sev­en to 10 days, see if your results have improved, based on your edits.

The SEO tac­tics that I’ve described are free and do work but they do not offer fast results. With some per­sis­tence, these ideas may just help your users find the answers they need.

HAVE YOU EVER HACKED A PROCESS?

by 2 Comments

Have you ever worked at a com­pa­ny and had to con­tend with con­vo­lut­ed process­es just to get your job done?

I have. I worked at one firm where some­thing as rou­tine as updat­ing a time sheet was a mul­ti-step process that involved log­ging on two web sites. This may have made sense to the depart­ment that cre­at­ed the sites but it sure made life dif­fi­cult for hun­dreds of employ­ees who were expect­ed to use the time sheet every day.

It’s a com­mon occur­rence. The book Hack­ing Work: Break­ing Stu­pid Rules for Smart Results argues that most businesses’s “love of bureau­cra­cy, lin­ger­ing tech­nol­o­gy, and deeply ingrained process­es” is mak­ing life unbear­able for thou­sands of employ­ees around the world. The book was list­ed as the Har­vard Busi­ness Review’s ten break­through ideas for 2010. Here’s an excerpt:

“Today’s top per­form­ers are tak­ing mat­ters into their own hands. They’re bypass­ing sacred struc­tures and break­ing all sorts of rules just to get their work done…More and more of us are find­ing that our work tools and struc­tures are com­plete­ly out of synch with what we need to do our best. Most of our dai­ly needs, dreams, desires, and goals are far ahead of our employ­ers’ tech­no­log­i­cal, pro­ce­dur­al, and social adop­tion curves.”

Like most peo­ple, I used to think of a “hack” as an act meant to do harm. But authors Bill Jensen and Josh Klein sug­gest that a hack can often be some­thing benev­o­lent: “It’s about mak­ing the sys­tem work for you, so you can take con­trol of your work­load, increase your pro­duc­tiv­i­ty, and help your com­pa­ny succeed—in spite of itself.”

This book made me think about labo­ri­ous tasks that I’ve wres­tled with in the past. Two examples:

  • I worked for a high-tech com­pa­ny that was bought by a multi­na­tion­al orga­ni­za­tion. After the dust set­tled, the tech­ni­cal com­mu­ni­ca­tions group was faced with a huge rebrand­ing effort includ­ing chang­ing tem­plates and copy­right con­tent, and replac­ing all old com­pa­ny names with the new com­pa­ny name. On my prod­uct team, I need­ed to replace hun­dreds of old com­pa­ny and prod­uct names. And it wasn’t a quick search and replace effort. It required me to review every instance because of rules about the company’s name and its place­ment with­in a sen­tence. How I’d do things dif­fer­ent­ly today: For all prod­uct and com­pa­ny names, I’d use vari­ables so that if copy­right­ed names changed again, I could change them in min­utes, not days.
  • At anoth­er com­pa­ny some years ago, I dis­trib­uted con­tent to sub­ject mat­ter experts for a tech­ni­cal review, and received dozens of com­ments back on a large doc­u­ment. So what did I do? Review the PDF file and com­pare it to the orig­i­nal source file sen­tence by sen­tence. I found myself think­ing, “Sure­ly, there’s a bet­ter way to man­age these reviews so I don’t have to do this com­par­i­son page by page.” How I’d do things dif­fer­ent­ly today: If I’m using the lat­est ver­sion of FrameMak­er or Robo­Help, I’d ful­ly embrace the fea­ture that enables me to import PDF anno­ta­tions back into my source files. Hours of time saved!

These are not so much “hacks” but just dif­fer­ent approach­es I’d take if faced with the same work. As for those time sheets? Per­haps I’d just blunt the tedi­um of the task by try­ing to update the time sheets less frequently.

COMPLACENCY AND TECHNICAL WRITERS

by 4 Comments

I’ve seen it hap­pen many times. Col­leagues who chal­lenge them­selves in their careers and nab a desir­able job with a sought-after title. Maybe the job is a Tech­ni­cal Com­mu­ni­ca­tions Man­ag­er role. Per­haps it’s a Senior Tech­ni­cal Writer position.

After they set­tle into the new role and demon­strate suc­cess for some peri­od of time, they appear to stop learn­ing. It’s as if they’ve reached their goal and don’t want to push them­selves any­more. Here are two exam­ples I’ve witnessed:

  • The man­ag­er who just wants to write. They love writ­ing but they’re not that keen on tech­nol­o­gy and they avoid terms like DITA and XML, even though more and more jobs require these skills.
  • The tech­ni­cal writer who works for a large well-known com­pa­ny that is strug­gling finan­cial­ly. He knows the com­pa­ny is going through chal­leng­ing times but doesn’t both­er apply­ing for any jobs out­side of the firm. He feels secure and can’t be both­ered to be proac­tive. One day, senior man­age­ment decides to lay off almost every­one in the divi­sion, includ­ing the tech­ni­cal writer. He’s unem­ployed for six months because he is now com­pet­ing with all the oth­er writ­ers who were laid off. He almost exhausts his sav­ings in the process.

It’s not unique to tech­ni­cal writ­ers and man­agers. I know some­one who worked for years as a mar­ket­ing con­sul­tant. When social media became more and more preva­lent, he dis­missed it as a fad, when it actu­al­ly became a require­ment for a job. If you were an employ­er and you had to choose between an eager can­di­date who was well versed in RSS feeds, blogs, and viral mar­ket­ing and an expe­ri­enced but expen­sive mar­ket­ing per­son who was still mired in the 1990s, who would you choose?

In my opin­ion, all of these peo­ple became com­pla­cent. They stopped car­ing about learn­ing and improving.

Why do peo­ple do this? Do these exam­ples ring a bell? Why do you think that some peo­ple fall into this rut?

Recent Blog Posts

About Me

Robert Desprez I have worked as a Vancouver technical writer for more than 20 years, working at Kodak, Boeing, Teck Resources, and FortisBC. In addition, I have worked as a writing instructor at Simon Fraser University in Vancouver.

Contact Me

Robert Desprez Com­mu­ni­ca­tions Inc.
North Van­cou­ver, British Columbia
Canada
Phone: 604–836-4290