Robert Desprez Communications

  • My Services
  • My Blog
  • About Me
  • Contact Me

A Rare Example of an Excellent Installation Guide For Home Use

November 25, 2018 by RDesprez Leave a Comment

The sup­port doc­u­men­ta­tion that accom­pa­nies most con­sumer prod­ucts is pret­ty poor.

A few years ago, our fam­i­ly bought a Mur­phy bed that took me two full days on a week­end to build. When the box was deliv­ered to our house, it weighed more than 50 kilo­grams and con­tained dozens of com­po­nents, includ­ing numer­ous bags of screws, bolts, and nuts. The bed includ­ed a 25-page instal­la­tion guide that most­ly relied on images. Here’s a scanned sam­ple of one of the pages (yes, I keep most user doc­u­men­ta­tion for per­son­al purchases):


 

Notice that the guide min­i­mizes the use of text, a stan­dard that Ikea, the world’s largest fur­ni­ture retail­er, whole­heart­ed­ly embraces. The order of steps is pre­sent­ed as a type of leg­end; the user needs to first look for label 34 and find it in the illus­tra­tion, then com­plete the steps shown in label 35, and so on. Oth­er than this map­ping exer­cise, I found that many of the pages in the guide were clut­tered. One of my most sig­nif­i­cant chal­lenges in assem­bling the bed was that the screws shown at the bot­tom of the page were not labelled in any of the bags that were packed in the box. There many instances where I found myself scru­ti­niz­ing a bag of screws—and there were at least 20 bags of them—to deter­mine if this was the right tool for a spe­cif­ic step.

Doc­u­men­ta­tion like this is more com­mon than not. When cus­tomers buy a $199 dress­er from a store like Ikea I believe they know the instruc­tions will be mediocre and that there is a chance that parts will be miss­ing. It’s a com­mon exam­ple of doc­u­men­ta­tion that is bare­ly “good enough.”

Know­ing that most con­sumer doc­u­men­ta­tion is poor at best, I was delight­ed to pur­chase a smart ther­mo­stat and dis­cov­er the doc­u­men­ta­tion was actu­al­ly good. Here’s an exam­ple of one of the pages of the instal­la­tion guide:

I love the use of ample white space, the clear and suc­cinct instruc­tions, and the excel­lent illus­tra­tions. In my expe­ri­ence, good illus­tra­tions are a rar­i­ty in documentation.

It is obvi­ous to me that the com­pa­ny’s design team (the com­pa­ny in this case is Nest) put in a lot of effort to make the prod­uct intu­itive and sim­ple. I was able to install the ther­mo­stat in about 30 min­utes with­out a glitch.

My only sug­ges­tion to the com­pa­ny’s sup­port team would be to include a user guide in the box. Cur­rent­ly, if you need step-by-step instruc­tions on oper­at­ing the ther­mo­stat, you need to vis­it Nest’s website.

If the online reviews are any indi­ca­tion, a lot of peo­ple love the Nest ther­mo­stat. Admit­ted­ly, it’s a pre­mi­um prod­uct so it’s design and doc­u­men­ta­tion is notice­ably bet­ter than many products.

Have you expe­ri­enced con­sumer doc­u­men­ta­tion that has impressed you?

Filed Under: Career Development, Robert Desprez | Vancouver technical writer | Blog Tagged With: consumer documentation, consumer user guide, Ikea, Installation guide, Nest

Seven Ways to Improve the Technical Writing Review Process

October 10, 2018 by RDesprez 4 Comments

Writ­ing and prepar­ing tech­ni­cal con­tent for a review can be seam­less or stress­ful, depend­ing on dead­lines, the tools and tech­nol­o­gy, and the team per­son­al­i­ties and dynam­ics.  Here are sev­en ways to make tech­ni­cal reviews easier.

  1. Lim­it the num­ber of  Sub­ject Mat­ter Experts (SMEs) to four or five peo­ple. I recent­ly worked with a client who was attempt­ing to get 20 peo­ple with dis­parate views to agree to a doc­u­ment. If some of those peo­ple don’t like each oth­er or are not moti­vat­ed to get the work done, shep­herd­ing the doc­u­ment towards the “fin­ish line” is close to impossible.
  2. Use a col­lab­o­ra­tion tool like Share­Point or Con­flu­ence. Send­ing out reviews by email has its share of lim­i­ta­tions. One of the main weak­ness­es is that SMEs can­not eas­i­ly see each oth­er com­ments. When there are dif­fer­ences of opin­ion on a cer­tain para­graph or sen­tence, it can cre­ate more work for tech­ni­cal writ­ers as they may need to fol­low-up with mul­ti­ple SMEs to rec­on­cile the con­flict­ing edits. Tools like Share­Point and Con­flu­ence enable SMEs to review con­tent online and see all the oth­er comments.
  3. For con­tentious top­ics, arrange SMEs to sit in the same room. If you expect that your SMEs will have strong opin­ions about a giv­en sub­ject, arrange to have them sit in the same room and dis­cuss the con­tent. Try­ing to get con­sen­sus via e‑mail is hard­er than face-to-face meetings.
  4. Ask that SMEs focus on review­ing the accu­ra­cy of the con­tent. Remind SMEs that you want them to focus on the accu­ra­cy of the con­tent, not the pre­sen­ta­tion or for­mat­ting or writ­ing styles.
  5. Con­sid­er pro­vid­ing sug­ges­tions on the type of feed­back you’d like. I can­not tell you how many times I’ve seen SMEs high­light a sen­tence and write “???”. If some­thing is con­fus­ing or mis­lead­ing, encour­age SMEs to rewrite it.
  6. Set expec­ta­tions about how the review cycle works. Remind the client that the review cycle typ­i­cal­ly takes two to three iter­a­tions and that the con­tent doesn’t always need to be “per­fect.” The nice thing about doc­u­ments is con­tent can always be revised and improved for a future release.
  7. Con­sid­er using out­lines. If con­tent is com­pli­cat­ed or the mate­r­i­al is con­tentious, I’ve found it’s a lot eas­i­er to revise an out­line than to revamp or restruc­ture exist­ing content.

What strate­gies or tac­tics do you use to expe­dite or improve the tech­ni­cal com­mu­ni­ca­tion review process?

Filed Under: Robert Desprez | Vancouver technical writer | Blog Tagged With: SMEs, Subject Matter Experts, Technical Writing Review Process

First Impressions of Adobe RoboHelp 2019

September 2, 2018 by RDesprez Leave a Comment

Adobe just released a new ver­sion of FrameMak­er and Robo­Help last month.  If you have used the appli­ca­tion for years, you might be for­giv­en for not even rec­og­niz­ing RoboHelp—it’s been com­plete­ly revamped.

First, for such an old pro­gram (more than 25 years!), Adobe has per­formed an “extreme makeover” when it comes to the user inter­face. It’s clean and mod­ern. It looks like a new application.

RoboHelp 2019 user interface

Adobe has bestowed Robo­Help with a min­i­mal­ist user inter­face. There are not dozens of icons to click like you see in an appli­ca­tion like Microsoft Word. Even though it looks dra­mat­i­cal­ly dif­fer­ent than old­er ver­sions of the pro­gram, I found myself being able to use it right away. How­ev­er, Adobe prob­a­bly rec­og­nized that not every­one wants to learn a new user inter­face so the com­pa­ny is also includ­ing Robo­Help Clas­sic 2019 for those users who pre­fer to work in famil­iar ways.

A Quick Way to Generate Output Files

I like the new way in which you can out­put files.

When you click the Quick Gen­er­ate icon, you can click the out­put you want to gen­er­ate. I like that you can cre­ate out­put files with­out a lot of con­fig­u­ra­tion. I also appre­ci­ate that you can keep work­ing while Robo­Help cre­ates the files in the back­ground. If you want to tweak set­tings for an out­put file, there’s still the Edit button.

Adobe Further Improves RoboHelp’s Search

Robo­Help 2019 builds on some of the improve­ments intro­duced in Robo­Help 2017. Most notably, Robo­Help 2017 includ­ed some wel­come improve­ments by dis­play­ing key­words as users type in the search field. For exam­ple, when I start typ­ing a search query about “con­tact­ing,” Robo­Help starts pro­vid­ing sug­ges­tions on the fly, sim­i­lar to Google’s search engine.

Robo­Help 2019 includes pre­dic­tive search but will also fix users’ typos.  For exam­ple, if I type “HTML5 out­pt,” the HTML5 Help auto­mat­i­cal­ly presents the cor­rect­ed results for me. Giv­en that many users may inad­ver­tent­ly add typos in their search queries, this is a wel­come addition.

RoboHelp 2019 Supports Git, HTML5, and Scalable Vector Graphics

Robo­Help also includes sup­port for Share­Point Online and Git, HTML5, Cas­cad­ing Style Sheets (CSS) 3, and Scal­able Vec­tor Graph­ics (SVG) images. Share­Point and Share­Point Online are not the same thing. With Share­Point Online, you can access inter­nal sites, doc­u­ments, and oth­er infor­ma­tion from anywhere—at the office, at home, or from a mobile device. Git is a ver­sion con­trol sys­tem for track­ing changes in com­put­er files and coor­di­nat­ing work on those files among mul­ti­ple people.

Over­all, I am impressed with the Adobe’s com­mit­ment to over­haul RoboHelp!

 

 

Filed Under: Help Authoring Tools, Robert Desprez | Vancouver technical writer | Blog, Technology Tagged With: Adobe, Adobe RoboHelp 2019, Help Authoring Tools, Review

Preparing Your Content for Bots? I Am Not.

July 4, 2018 by RDesprez 3 Comments

Pre­dic­tions that tech­ni­cal writ­ers will be writ­ing for bots any time soon are overblown. From one upcom­ing tech­ni­cal writ­ing con­fer­ence, here is a sam­pling of some of the upcom­ing presentations:

  • “Con­nect­ing a Chat­bot to Your Tech­ni­cal Content.”
  • “Your Chat­bot Can Lit­er­al­ly Talk Back.”
  • “Prepar­ing for Change in a World of Non-Stop Change: Beyond Chat­bots and Voice.”

Ear­li­er this year, I watched two webi­na­rs on how tech­ni­cal writ­ers can write con­tent for bots. One of the pre­sen­ters acknowl­edged that he felt that writ­ing for bots is in its “infan­cy.” To me, the take­away is this trend isn’t going to take off any­time soon, at least in the tech­ni­cal writ­ing community.

Tech­nolo­gies like bots are tout­ed by indi­vid­u­als who orga­nize tech­ni­cal writ­ing con­fer­ences and con­sul­tants who are more than hap­py to ped­dle clients the “next big thing.” There’s also a lot of fear about arti­fi­cial intel­li­gence and how the robots will usurp all of our jobs. From my per­spec­tive, in my home­town of Van­cou­ver, BC, I find that the adop­tion of new tech­nolo­gies with­in the tech­ni­cal writ­ing com­mu­ni­ty is often slow.

Here is an exam­ple I can share to illus­trate the point. For years, we heard about using the ben­e­fits of struc­tured author­ing using data mod­els for author­ing and pub­lish­ing like Dar­win Infor­ma­tion Typ­ing Archi­tec­ture (DITA). Ten years ago, I was writ­ing in XML using DITA. It seemed like it was going to be the next thing. I was a believ­er. But my unwa­ver­ing faith in all things DITA waned when I real­ized it was a mar­gin­al play­er in a city with a flour­ish­ing high-tech com­mu­ni­ty that employs more than 100,000 peo­ple. More often than not, tech­ni­cal writ­ing depart­ments are writ­ing unstruc­tured con­tent using tools like FrameMak­er, Mad­Cap Flare, wikis, and Microsoft Word.

I am sure that com­pa­nies like Adobe and Mad­Cap will soon intro­duce sup­port for bots. But even when sup­port is intro­duced, I am not expect­ing the change will rev­o­lu­tion­ize life for tech­ni­cal writ­ers in the short term.

Don’t get me wrong: I am not ignor­ing bots. But I don’t feel like I need to jump on the band­wag­on either. There is fre­quent­ly a chasm between what is being pro­mot­ed at con­fer­ences and in webi­na­rs and the real­i­ty of over­worked tech­ni­cal writ­ing depart­ments who may not have time to quick­ly adopt new technologies.

Filed Under: Career Development, Help Authoring Tools, Robert Desprez | Vancouver technical writer | Blog, Technology Tagged With: bots, technical writing, technologies

List of Online Webinars and North American Conferences for Technical Writers

May 10, 2018 by RDesprez Leave a Comment

There’s no short­age of train­ing web sites, webi­na­rs, and con­fer­ences to keep your skills sharp.

Adobe’s blog:
https://blogs.adobe.com/techcomm/

MadCap’s free webinars:
https://www.madcapsoftware.com/resources/recorded-webinars.aspx

Scrip­to­ri­um Pub­lish­ing offers time­ly and insight­ful thoughts on tech­ni­cal writ­ing trends:
https://www.scriptorium.com/blog/

The Soci­ety for Tech­ni­cal Com­mu­ni­ca­tion (STC) also offers webi­na­rs and cours­es for a fee:
https://www.stc.org/education/

Here’s a list of upcom­ing con­fer­ences this year in North America.

Lava­con, Octo­ber 21–24, 2018, New Orleans, LA
http://lavacon.org

Mad­World Con­fer­ence, June 3–6, 2018, San Diego, CA
http://www.madcapsoftware.com/events/madworld/

STC annu­al con­fer­ence, May 20–23, 2018, Orlan­do, FL
http://summit.stc.org/

Write the Docs + Open Help Cincin­nati, August 18–22, Cincin­nati, OH
http://www.writethedocs.org/conf/cincinnati/2018/

Writ­er­sUA User Assis­tance Boot Camp, Oct 4–5, 2018, Raleigh, NC
http://east.writersua.com/

How do you keep your skills up to date? Any oth­er North Amer­i­can con­fer­ences that I should add?

Filed Under: Career Development, Robert Desprez | Vancouver technical writer | Blog Tagged With: conferences, technical writing, training

  • « Previous Page
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • …
  • 19
  • Next Page »

About Robert Desprez

I have worked as a Vancouver technical writer for more than 20 years, working at some of British Columbia's largest high-tech firms. I have served in leadership positions for the Society for Technical Communication and have worked as a writing instructor at Vancouver's Simon Fraser University.

Robert Desprez Follow 1,144 237

Vancouver Technical Writer. Former Instructor at Simon Fraser University. Dog Lover. Coffee Drinker. Tennis and Piano Player.

robert_desprez
robert_desprez avatar; Robert Desprez @robert_desprez ·
2 May 1918126029463536113

This productivity poison is exhausting you /via @globeandmail

Image for twitter card

This productivity poison is exhausting you

Constantly shifting your attention undermines what is your super power in most knowledge jobs. How you anticipate an...

www.theglobeandmail.com

Reply on Twitter 1918126029463536113 Retweet on Twitter 1918126029463536113 0 Like on Twitter 1918126029463536113 0 Twitter 1918126029463536113
robert_desprez avatar; Robert Desprez @robert_desprez ·
24 Apr 1915491435350253736

Google forcing some remote workers to come back 3 days a week or lose their jobs

Image for twitter card

Google forcing some remote workers to come back 3 days a week or lose their jobs

Several units within Google have told remote staffers that their roles may be at risk if they don't start showin...

cnb.cx

Reply on Twitter 1915491435350253736 Retweet on Twitter 1915491435350253736 0 Like on Twitter 1915491435350253736 0 Twitter 1915491435350253736
robert_desprez avatar; Robert Desprez @robert_desprez ·
16 Apr 1912364221582758283

Image for twitter card

As Canadians cancel trips due to Trump, the U.S. tourism industry could lose billions

The Trump administration's attacks on its northern neighbor have been met with confusion and anger by some Canadians...

www.npr.org

Reply on Twitter 1912364221582758283 Retweet on Twitter 1912364221582758283 0 Like on Twitter 1912364221582758283 0 Twitter 1912364221582758283
robert_desprez avatar; Robert Desprez @robert_desprez ·
13 Apr 1911507080504303659

Image for twitter card

How to awaken Canada’s sleeping economic giant

Recent interviews with industry leaders and experts point toward 10 areas where actionable strategies are needed – ...

www.theglobeandmail.com

Reply on Twitter 1911507080504303659 Retweet on Twitter 1911507080504303659 0 Like on Twitter 1911507080504303659 0 Twitter 1911507080504303659
Load More

Recent Blog Posts

  • ChatGPT: The AI-Powered Proofreader
  • Four Ways Confluence Could Be Better
  • First impressions of MadCap’s purchase of IXIASOFT
  • Online Conferences for Technical Writers in 2023

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

  • Email
  • LinkedIn
  • Twitter

Copyright © 2025  · Robert Desprez Communications Inc.