Robert Desprez Communications

Improve your training with practice and feedback

by Leave a Comment

Have you ever attend­ed a course or train­ing ses­sion that missed its mark?

Most of the cours­es that I have tak­en haven’t met my expec­ta­tions for dif­fer­ent rea­sons. In uni­ver­si­ty, there was the pro­fes­sor who’d lec­ture for an hour, lulling stu­dents to sleep. There was the work­place train­er who focused on how the soft­ware worked but not the tasks that stu­dents (or learn­ers) required. There was the employ­ee who was threat­ened about shar­ing too much for fear of los­ing her job so she with­held knowl­edge, ren­der­ing the train­ing almost use­less. I could go on.

In my expe­ri­ence, senior man­age­ment holds the belief that any­one can train. But few peo­ple do it well.

Too often train­ing is just a “pletho­ra of regur­gi­tat­ed knowl­edge,” said Jim Tall­man, pres­i­dent of North Pacif­ic Train­ing & Per­for­mance Inc. Tall­man spoke at the Cana­da West Chap­ter of the Soci­ety for Tech­ni­cal Com­mu­ni­ca­tion for a pro­fes­sion­al devel­op­ment ses­sion on Sep­tem­ber 13th.

Train­ing that focus­es on rehash­ing knowl­edge doesn’t help learn­ers per­form their jobs bet­ter and pro­vides incon­sis­tent results, he said.  Some exam­ples of inef­fec­tive train­ing include:

  • The cur­ricu­lum fol­lows the­o­ry, not skills or tasks that one per­forms on the job.
  • Con­tent fol­lows course design, not a task analysis.
  • Exam­ples focus on sys­tem fea­tures, not work­place processes.
  • The course high­lights the knowl­edge of the sys­tem, not improved performance.
  • The instruc­tor nev­er stops talking.

A better way to train

An alter­na­tive method of train­ing focus­es on improv­ing the learn­ers’ skills. Some ele­ments of effec­tive training:

  • Task analy­sis dri­ves course design.
  • Cur­ricu­lum reflects the job.
  • Con­tent is prac­tice-based and learn­er paced.
  • Course results in improved job performance.

He said: “This is the pre­ferred way…that train­ing should be designed to give learn­ers what they need and clients their money’s worth. Instruc­tion is based on how learn­ers learn and not on how much the train­er can demo his or her prowess in the field.”

Train­ing should be ide­al­ly 30 per­cent pre­sen­ta­tion or lec­ture and 60 per­cent hands-on (such as exer­cis­es or activ­i­ties), said Tall­man. The final 10 per­cent of the course should be allo­cat­ed on feed­back so that learn­ers can improve. Most tra­di­tion­al train­ing is reversed with the instruc­tor talk­ing most of the time and learn­ers’ eyes glaz­ing over after 20 min­utes of lec­ture, he said.

In addi­tion, effec­tive train­ing should be also mean­ing­ful, mem­o­rable, moti­va­tion­al, and mea­sur­able, Tall­man said.

  • Mean­ing­ful: Train­ing should be rel­e­vant for learn­ers so they can per­form key tasks rel­e­vant to their jobs.
  • Mem­o­rable: Learn­ers need to remem­ber their train­ing after the course. Job aids, hand­outs, and quick ref­er­ence cards may be able to assist.
  • Moti­va­tion­al: Train­ing should moti­vate learn­ers in the class­room so that they want to apply the new skills.
  • Mea­sur­able: Effec­tive train­ing teach­es new skills that can be observed. “Good learn­ing events stress observ­able behav­iors, give learn­ers suf­fi­cient prac­tice over time, and pro­vide per­for­mance feedback.”

Not sur­pris­ing­ly, Tall­man’s train­ing focused on prac­tice and feed­back so that learn­ers could improve. This was an excel­lent presentation!

How to use illustrations to make your
technical docs clearer

by 3 Comments

Images can be a suc­cinct and effec­tive way to con­vey a mes­sage. Yet I don’t see many illus­tra­tions being used in tech­ni­cal com­mu­ni­ca­tions. Many writers—including me—don’t think their strength is illustrating.

Dan Roam, in his book The Back of the Nap­kin, argues that one does­n’t have to be a gift­ed artist or use Adobe Illus­tra­tor or Microsoft Pow­er­Point to cre­ate effec­tive images. Draw­ings can be as sim­ple as hand-drawn pic­tures, he says. Indeed, his book is brim­ming  with draw­ings that resem­ble doo­dles. One of my favorite things about Roam’s book is that he offers a frame­work that helps read­ers think about how to approach illustrating.

Here are some of the draw­ings he discusses:

  • Por­traits: To explain a con­cept that address­es the “who” or “what,” Roam rec­om­mends using a qual­i­ta­tive dia­gram. For exam­ple, many peo­ple strug­gle with under­stand­ing the term “meta­da­ta.” You could try to define it (such as “it’s data about data.”) But that def­i­n­i­tion often leaves peo­ple still scratch­ing their heads. An alter­na­tive solution—you could draw it.

Example of metadata

In short, meta­da­ta pro­vides more details about a doc­u­ment, such as who wrote the file, when the per­son wrote it, the point of the doc­u­ment, and so on.

  •  Charts: If you’re try­ing to com­mu­ni­cate a quan­ti­ty, writ­ing about it may suf­fice. But if you’re per­form­ing a com­par­i­son, a pie chart or bar chart is the best choice. Here’s a fic­ti­tious example:

example_chart

  • Time­lines: To explain a process or work­flow, you could try explain­ing each step. Anoth­er way to accom­plish the same thing is by using a sim­ple work­flow dia­gram, which explains “when” some­thing hap­pens in a process. For work­flows, I fre­quent­ly use Microsoft Office’s Smar­tArt fea­ture. Here’s a sam­ple work­flow I cre­at­ed that con­veys a com­mon­ly used approach to cre­at­ing tech­ni­cal documents:

Authoring_process

  • Maps: When explain­ing the rela­tion­ship of one object to anoth­er, Roam rec­om­mends you use a map. When I think of maps, I tend to think of street maps. But that’s too nar­row a def­i­n­i­tion. Maps can show all sorts of things. From Roam’s book, here’s one exam­ple that explains the rela­tion­ship among objects:

Example of a map

Here’s anoth­er screen cap­ture from Roam’s book that shows an orga­ni­za­tion­al chart, which is just anoth­er type of map:

Organizational chart

  •  Flow­charts:  Flow­charts are tools that explain “how” a process works. If you’re seri­ous about flow­charts, you could use Visio. For end-user doc­u­men­ta­tion, I find Visio dia­grams too tech­ni­cal look­ing and uninvit­ing. I cre­at­ed this sim­ple flow­chart in Pow­er­Point that explains one way to review tech­ni­cal documents:

Example of flowchart

In this blog entry, I’ve just scratched the sur­face of Roam’s book. The Back of the Nap­kin is well worth a read for tech­ni­cal writ­ers who want to diver­si­fy their skill set and use visu­al think­ing to work through com­plex tech­ni­cal concepts.

HTML5 or EPUB: What is best for technical documentation?

by 2 Comments

When you cre­ate doc­u­men­ta­tion for tablets or smart­phones, should you cre­ate an EPUB file or an HTML5 file?  As usu­al, it depends on your audience.

What is an EPUB file and how does it differ from HTML5?

An EPUB doc­u­ment is an XML file that is zipped file with the .epub exten­sion. You cre­ate EPUB files using Microsoft Word, Adobe InDe­sign, and help author­ing tools such as Mad­Cap Flare and Adobe Robo­Help. This enables users to read the file in Adobe Dig­i­tal Edi­tions, or iBooks, Apple’s free e‑reader for iOS.

HTML5 is not soft­ware that has to be installed but rather a new ver­sion of HTML that appears in your brows­er. It’s a work in progress. Safari and Chrome pro­vide good sup­port for HTML5 where­as Inter­net Explor­er has been slow to sup­port it.

Why would you create an EPUB file?

The main advan­tage of an EPUB file is that is changes the flow of the text, based on the device you have. If your users are view­ing your con­tent on an iPhone, the pre­sen­ta­tion of the con­tent appears dif­fer­ent­ly than if it is viewed on a PC or an iPad. For exam­ple, see the fol­low­ing two screen shots:

EPUB file shown on an iPad
EPUB file shown on an iPad
EPUB on an iPhone
EPUB on an iPhone

With EPUB files, you can also choose the fixed lay­out option as well. Fixed lay­out EPUB files are per­fect for cook­books, illus­trat­ed books, and some text­books. With the fixed lay­out func­tion­al­i­ty you can embed fonts, choose par­tic­u­lar text sizes, and pre­cise­ly posi­tion images. Basi­cal­ly, fixed lay­out options give con­tent cre­ators greater con­trol over the pre­sen­ta­tion of a doc­u­ment. For the tech­ni­cal details of a fixed lay­out option for EPUB, see the Fixed Lay­out Doc­u­ment sec­tion of the Inter­na­tion­al Dig­i­tal Pub­lish­ing Forum web site.

One dis­ad­van­tage of an EPUB file is that it may require your users to install soft­ware such as iBooks, which is not pre-installed on iPads or iPhones.

Why would you create an HTML5 file?

You prob­a­bly want to con­sid­er cre­at­ing an HTML5 file when your users are run­ning browsers (such as Safari or Chrome) that sup­port it. If you are con­fi­dent that your users are using one of these browsers, it’s eas­i­er for them to view your work. There is no extra app to install.

Anoth­er advan­tage of HTML5 is that if your user assis­tance is avail­able in a brows­er, any revi­sions to the con­tent will imme­di­ate­ly be seen by your users. With an EPUB file, there’s the addi­tion­al work of cre­at­ing the lat­est EPUB file and dis­trib­ut­ing it again to your users.

HTML5 also sup­ports offline support—meaning that you can view the con­tent when you have an Inter­net con­nec­tion, your brows­er caches the con­tent, and then you can view the same con­tent when you are offline. This may be per­fect for users who need user assis­tance but do not have a reli­able net­work connection.

Other Resources

* What is EPUB 3? by Matt Gar­rish ( a free O’Reil­ly book).

* Eliz­a­beth Castro’s book EPUB Straight to the Point. 

* Test your brows­er for HTML5 sup­port

*A free online book: Dive into HTML5 by Mark Pilgrim.

Is writing for mobile the next big thing?

by 10 Comments

With all the news about the sky­rock­et­ing demand for smart­phones over­tak­ing com­put­er pur­chas­es, you might think that tech­ni­cal writ­ers would increas­ing­ly need to focus on writ­ing and deliv­er­ing user assis­tance for mobile devices.

For tech­ni­cal writ­ers, writ­ing for mobile appears to be the next big thing. Here are a few examples:

  • Mobile devices will be the pri­mary con­nec­tion tool to the Inter­net for most peo­ple by 2020, accord­ing to the Pew Research service.
  • Ref­er­ences to mobile phones and tablets are abun­dant at the Writ­er­sUA con­fer­ence and the upcom­ing Soci­ety for Tech­ni­cal Com­mu­ni­ca­tion conference.
  •  Help author­ing tools such as Mad­Cap Flare and Robo­Help tout that they sup­port pub­lish­ing con­tent for mobile devices using the ePub output.
  • There’s even a book ded­i­cat­ed to the top­ic called Devel­op­ing User Assis­tance For Mobile Apps by Joe Welinske.

So along with social media, one might think that cre­at­ing user assis­tance for mobile devices will rev­o­lu­tion­ize the way we work. There’s one prob­lem though.  In the last year, I have yet to see one job descrip­tion in Van­cou­ver that explic­it­ly refers to prepar­ing con­tent for mobile devices. When it comes to tech­ni­cal writ­ing oppor­tu­ni­ties, Van­cou­ver is no Sil­i­con Val­ley but it’s not unusu­al to see five to 10 adver­tised jobs per month.

I don’t think any­one can argue that cre­at­ing user assis­tance for mobile devel­op­ment is too new. Accord­ing to Apple’s web site, there are report­ed­ly 500,000 appli­ca­tions for the iPhone and iPad. There are also thou­sands of appli­ca­tions that run on the Android oper­at­ing sys­tem.  And smart­phones have been avail­able for years. So why is there not a surge in demand for user assis­tance for mobile devices? Some guesses:

  • Soft­ware devel­op­ers are writ­ing the con­tent. While the user assis­tance writ­ten by devel­op­ers may not be pro­fes­sion­al­ly writ­ten and for­mat­ted, per­haps man­age­ment feels that the con­tent  is “good enough”? After all, if a mobile app requires a lot of doc­u­men­ta­tion, it prob­a­bly means that it’s dif­fi­cult to use. Users expect apps to be simple.
  • Per­haps writ­ing for mobile is not big as pre­dict­ed. Employ­ers in Van­cou­ver are not clam­or­ing for writ­ers with mobile expe­ri­ence.  To be fair, I searched for “tech­ni­cal writer mobile” on the U.S. job site www.dice.com and found that 41 of 649 jobs men­tioned “mobile” in the job descrip­tions. Hard­ly a tsunami!
Do you think writ­ing user assis­tance for mobile will be the next thing? Why is there not a stronger demand? I’d be inter­est­ed in your thoughts.

 

THE POWER OF SAYING I DO NOT KNOW

by 2 Comments

Knowl­edge is pow­er, as the old cliché goes.

For any­one who has worked in high-tech, it shouldn’t come as a big sur­prise when I assert that mas­ter­ing cer­tain tech­nolo­gies can mean a pay raise or more respon­si­bil­i­ties. Employ­ees that “don’t keep up” or who don’t appear to pos­sess the lat­est tech­ni­cal knowl­edge may not be con­sid­ered seri­ous or ambitious.

Most peo­ple work­ing in IT tend to be men. In my opin­ion, most men in high-tech pride them­selves on their tech­ni­cal prowess and are reluc­tant to admit that they don’t know all the answers. I have attend­ed many meet­ings in which you have two or more strong-willed guys argu­ing about some tech­ni­cal detail. Tem­pers inevitably flare and posi­tions become entrenched.

Inc. mag­a­zine recent­ly pub­lished a short arti­cle called the “The Pow­er of Say­ing ‘I Don’t Know.’” Here’s an excerpt: “In today’s ultra com­pet­i­tive work envi­ron­ment, many peo­ple feel the need to be ‘super work­ers’ and have an answer to every ques­tion. But, it’s not always a good thing if you have peo­ple who work for you that are afraid to admit they don’t know something…”

In con­trast to many IT work­ers, I believe that many tech­ni­cal writ­ers and instruc­tion­al design­ers are will­ing to admit gaps in knowl­edge. After all, our jobs require us to research often basic infor­ma­tion for new users. With that in mind, we have to ask sub­ject mat­ter experts some pret­ty rudi­men­ta­ry yet spe­cial­ized ques­tions because we need to relay that con­tent to users. Our jobs require a healthy dose of humility.

Of course, I’m mak­ing gen­er­al obser­va­tions. But I’d haz­ard a guess that a sig­nif­i­cant por­tion of IT work­ers want to feel like they know all the answers. For writ­ers, this will­ing­ness to admit we are not “all know­ing” may be one dif­fer­en­tia­tor from our peers.

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