Robert Desprez Communications

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

How checklists can make your job easier

February 27, 2022 by RDesprez Leave a Comment

As a tech­ni­cal writer who relies on check­lists for aspects of my work, I just had to read a book called The Check­list Manifesto.

Atul Gawande, the author of the book and a sur­geon and a pro­fes­sor at Har­vard Med­ical School, argues that check­lists are essen­tial in all facets of society—from deliv­er­ing qual­i­ty health care, to design­ing and con­struct­ing build­ings, to research­ing what invest­ments to buy, to assist­ing pilots to han­dle emer­gen­cies, such as engine fail­ures. Gawande says the rea­son that mis­takes occur is due to the vol­ume of infor­ma­tion and increased com­plex­i­ty in so many aspects of soci­ety. Despite the addi­tion­al train­ing that is required in so many jobs and an abun­dance of tech­nol­o­gy, we still often fail to deliv­er the intend­ed results.

Check­lists can mit­i­gate some of these mis­takes. One exam­ple he includes is how a sim­ple check­list can help over­whelmed med­ical pro­fes­sion­als go over some of the basics before oper­at­ing on patients. Before surgery, doc­tors are sup­posed to per­form the following:

  1. Wash their hands with soap.
  2. Clean the patien­t’s skin with an antiseptic. 
  3. Put ster­ile drapes over the entire patient.
  4. Wear a mask, hat and ster­ile gown.
  5. Put a ster­ile dress­ing over the inser­tion site of the “cen­tral line,” a catheter placed in a large vein in the neck, chest, groin, or arm. 

Gawande acknowl­edges these steps are con­sid­ered “no-brain­ers.” But in one study, doc­tors for­got to per­form at least one of pre­vi­ous steps more than 30 per­cent of the time.

I think check­lists can be invalu­able for cer­tain aspects of tech­ni­cal writ­ing. In my cur­rent con­tract, cre­at­ing a check­list helps me iden­ti­fy and fix the com­mon for­mat­ting areas in more than 40 local­ized doc­u­ments. Are the trans­lat­ed notes and warn­ings in a doc­u­ment dis­play­ing prop­er­ly? Are the local­ized cross-ref­er­ences appear­ing as intend­ed? Are the French screen cap­tures dis­play­ing prop­er­ly? Each local­ized doc­u­ment, which can run from 150 to 1,000 pages, may con­tain a hand­ful of prob­lems that need to be fixed. In short, the hum­ble check­list helps me fix the prob­lems before I send it for an inter­nal review.

Yet, despite the use­ful­ness of check­lists, Gawande notes that peo­ple may be reluc­tant to use them. He writes:

“We don’t like check­lists. They can be painstak­ing. They’re not much fun. But I don’t think the issue here is mere lazi­ness. There’s some­thing deep­er, more vis­cer­al going on when peo­ple walk away not only from sav­ing lives but from mak­ing mon­ey. It some­how feels beneath us to use a check­list, an embar­rass­ment. It runs counter to deeply held beliefs about how the tru­ly great among us—those we aspire to be—handle sit­u­a­tions of high stakes and com­plex­i­ty. The tru­ly great are dar­ing. They impro­vise. They do not have pro­to­cols and check­lists. Maybe our idea of hero­ism needs updating.”

Gawande’s quote res­onat­ed with me because I have occa­sion­al­ly come across writ­ers who are reluc­tant to use them. Maybe they con­sid­er the check­list to be too sim­ple? Per­haps they feel it’s an affront to their knowl­edge? Oth­ers prob­a­bly don’t want to go to the effort of cre­at­ing or fol­low­ing one. What­ev­er the rea­son, I feel that check­lists can be indis­pens­able when you have a large vol­ume of work that con­tains spe­cif­ic tasks that needs to checked.

Filed Under: Career Development, Professional Development, Robert Desprez | Vancouver technical writer | Blog Tagged With: career development, localizations, professional development, translations

Online conferences for technical writers in 2022

January 30, 2022 by RDesprez Leave a Comment

Here’s a list of inter­est­ing North Amer­i­can and vir­tu­al con­fer­ences. With the pan­dem­ic still with us, it seems that the num­ber of con­fer­ences has dwin­dled, com­pared to pre­vi­ous years.

Lava­con, Octo­ber 23 to 26, 2022, New Orleans, LA
http://lavacon.org

Mad­World Con­fer­ence, June 12 to 15, 2022, Austin, TX and online ver­sion
Mad­World

STC annu­al con­fer­ence, May 15 to 18, 2022, Rose­mont, IL
http://summit.stc.org/

Write the Docs, May 22 to 24, 2022, Port­land, OR
Write the Docs

Filed Under: Professional Development, Robert Desprez | Vancouver technical writer | Blog, Technology, Training Tagged With: career development, conferences, technical writer | Blog, technical writing, vancouver technical writer

Streamline your MadCap Flare search results

April 17, 2021 by RDesprez Leave a Comment

Tech­ni­cal writ­ers with large help projects may want to con­sid­er imple­ment­ing Mad­Cap Flare’s search fil­ter func­tion­al­i­ty to help users stream­line their search results.

By default, Flare cre­ates HTML5 files with­out search fil­ters. By tag­ging your con­tent with meta­da­ta and com­plet­ing some relat­ed steps, you can cre­ate help with fil­ters that you define. For exam­ple, when users search for a term, they can select the type of con­tent they want. The fol­low­ing screen cap­ture shows a user who typed Login in the search field and is look­ing for trou­bleshoot­ing content. 

Flare’s search engine will then only dis­play con­tent relat­ed to the Login search term that is also tagged as trou­bleshoot­ing material.

How to set up search filters

As Flare has already writ­ten doc­u­men­ta­tion on this fea­ture, I have includ­ed the main steps and linked to Flare’s help top­ics. The fol­low­ing steps assume you already have some famil­iar­i­ty with Flare. 

Note: If you click each of the links in the fol­low­ing steps, you will dis­cov­er that there are about 35 steps to per­form in mul­ti­ple and seem­ing­ly dis­parate areas of Flare’s inter­face. If you make a mis­take in any of steps, your out­putted help may not include search fil­ters. I think this is one of the fea­tures in Flare that could def­i­nite­ly be simplified—if I attempt­ed to recre­ate each of the steps and include screen cap­tures, I could eas­i­ly write the equiv­a­lent of 10 pages of content.

Here are the main steps:

  1. Add a fil­ter set to your project in the Project Orga­niz­er under the Advanced fold­er. For more infor­ma­tion, see https://help.madcapsoftware.com/flare2020r3/Content/Flare/Search/Search-Filter-Sets/Adding-Search-Filter-Sets-Projects.htm
  2. Add meta­da­ta or con­cepts to your top­ics in Flare. This step involves tag­ging all your top­ics into cat­e­gories. For exam­ple, if my Flare project con­tains trou­bleshoot­ing top­ics, I will need to tag each trou­bleshoot­ing top­ic with a “trou­bleshoot­ing” con­cept. The good news is that I found this step to be pret­ty quick. There are dif­fer­ent ways to tag your con­tent; I end­ed up using the “drag-and-drop method.” See https://help.madcapsoftware.com/flare2020r3/Content/Flare/Concepts/Inserting-Concepts1.htm
  3. Cre­ate a search fil­ter, which lets users nar­rows their search based on the con­cepts you’ve added to top­ics. For more infor­ma­tion, see https://help.madcapsoftware.com/flare2020r3/Content/Flare/Search/Search-Filter-Sets/Creating-Search-Filters.htm
  4. Add a search bar to an HTML5 skin. This step is just a quick check to make sure the search bar is con­fig­ured to dis­play in the head­er. See https://help.madcapsoftware.com/flare2020r3/Content/Flare/Search/Required-Activities/Including-Search-Bars.htm#HowtoEnabletheSearchBarinanHTML5Skin
  5. Asso­ciate a skin with a tar­get. This is also a quick step to make sure your edit­ed skin appears in the tar­get. See https://help.madcapsoftware.com/flare2020r3/Content/Flare/Skins/Process/Associating-Skins-Targets1.htm
  6. Asso­ciate a search fil­ter set with a tar­get. See https://help.madcapsoftware.com/flare2020r3/Content/Flare/Search/Search-Filter-Sets/Associating-Search-Filter-Set-Target.htm

Although there is some plan­ning and effort to imple­ment search fil­ters, most of these steps will only need to be per­formed once.

Filed Under: Help Authoring Tools, Professional Development, Robert Desprez | Vancouver technical writer | Blog, Training

Online conferences for technical writers in 2021

March 20, 2021 by RDesprez Leave a Comment

Here’s a list of inter­est­ing con­fer­ences this year.

Evo­lu­tion of TC 2021 con­fer­ence, June 9 to 11, 2021
https://evolution-of-tc.com/

Lava­con, Octo­ber 24 to 27, 2021
http://lavacon.org

Mad­World Con­fer­ence, Octo­ber 3 to 6, 2021, Austin, Texas
https://www.madcapsoftware.com/madworld-conferences/madworld-2021/#content

STC annu­al con­fer­ence, June 5 to 9, 2021
http://summit.stc.org/

Tcworld con­fer­ence, Novem­ber 9 to 11, 2021
https://www.technical-communication.org/tekom/conferences/conferences-overview

Write the Docs, April 25 to 27, 2021
https://www.writethedocs.org/conf/portland/2021/

Writ­er­sUA UX Writer Con­fer­ence, June 8 to 9, 2021
https://welinske.com/writersua-conferences/

Any oth­ers I’ve missed?


Filed Under: Robert Desprez | Vancouver technical writer | Blog Tagged With: conferences, technical writing, vancouver technical writer

My impressions of the MadCap Flare certification

December 5, 2020 by RDesprez Leave a Comment

I am pleased that I recent­ly earned my Mad­Cap Flare Advanced Devel­op­er cer­ti­fi­ca­tion test. This blog post shares my impres­sions of the test and how it might be improved.

What is Flare and the certification test?

Mad­Cap Flare helps you author tech­ni­cal doc­u­men­ta­tion for online help, user man­u­als, soft­ware doc­u­men­ta­tion, and oth­er con­tent. Flare pro­vides func­tion­al­i­ty to devel­op, man­age, and pub­lish con­tent to sev­er­al for­mats, such as print, desk­top, and mobile devices.

The Mad­Cap Flare Advanced Devel­op­er cer­ti­fi­ca­tion is an online test con­sist­ing of 50 ques­tions, with an allot­ted test time of 75 min­utes. Unan­swered ques­tions are con­sid­ered incor­rect. To pass the test, you need a score of 70 per­cent or more.

Assum­ing you pass the test, you then need to sub­mit a sim­ple Flare project that con­tains at least:

  • Twelve top­ics
  • Six links
  • Three images
  • One skin
  • One mas­ter page
  • Two con­di­tion tags
  • Two tar­gets

Mad­Cap rec­om­mends that the sub­ject of the help project be about a sports team or a place, such as a city, coun­try, or a tourist attrac­tion. I cre­at­ed a sim­ple help project that high­lights some of the tourist sites in West and North Vancouver.

How I studied for the test

Scott DeLoach’s book Mad­Cap Flare 2020: The Defin­i­tive Guide is an excel­lent resource to study for the test. The book cov­ers all of Flare’s main fea­tures and includes sam­ple ques­tions and answers for the test. Mad­Cap has also added some sam­ple ques­tions to its web­site.

My impressions of the test

As DeLoach’s book is about 500 pages, you are going to need to spend some time read­ing, sum­ma­riz­ing, and mem­o­riz­ing the mate­r­i­al. I then spent time review­ing the sam­ple ques­tions in the book and research­ing the ques­tions that I did not imme­di­ate­ly know. Also, the test is not free—it’s $149 US so I rec­om­mend you study rea­son­ably hard so that you don’t have to pay again to re-take it.

The test itself is chal­leng­ing but fair. If you’ve stud­ied and you use Flare on a reg­u­lar basis, most of the ques­tions will be famil­iar. Occa­sion­al­ly, though, there are some ques­tions sprin­kled through­out the test that are hard­er to answer, such as “What char­ac­ter is used to sep­a­rate first and sec­ond-lev­el index entries?” This is a sam­ple ques­tion that appears in DeLoach’s book so I am hope­ful­ly not reveal­ing too much.

The test could be improved by per­haps incor­po­rat­ing sce­nar­ios that a writer might face in the work­place and how one could use Flare to over­come those chal­lenges. Here are a few sam­ple ideas:

  • Cre­at­ing tech­ni­cal doc­u­men­ta­tion when prod­uct names keep chang­ing (an all-too-com­mon scenario).
  • Think­ing about sin­gle-sourc­ing best practices.
  • Cre­at­ing dif­fer­ent tar­gets using conditions.
  • Set­ting up con­tent so it can eas­i­ly viewed on tablets and mobile devices.
  • Work­ing with Flare con­tent that resides in a con­tent man­age­ment system.

Over­all, I am glad I took the test. Even though I use Flare almost every day when work­ing, I learned a lot by going through the process.

Filed Under: Robert Desprez | Vancouver technical writer | Blog

  • « Previous Page
  • 1
  • 2
  • 3
  • 4
  • …
  • 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,184 239

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 Oct 1973868879261938086

Image for twitter card

The magic of AI is giving way to complaints about workslop

A team from Better Up Labs and the Stanford Social Media Lab define workslop as ‘AI generated work content tha...

www.theglobeandmail.com

Reply on Twitter 1973868879261938086 Retweet on Twitter 1973868879261938086 0 Like on Twitter 1973868879261938086 0 Twitter 1973868879261938086
robert_desprez avatar; Robert Desprez @robert_desprez ·
2 Oct 1973599012268941339

What a great website to book a BC ferry, if they are reserved. I just bought Vedran B a coffee on @buymeacoffee! 🎉

You can support them here —

Image for twitter card

Vedran B

I created https://nextsailing.ca as a free tool to help locals from the Lower Mainland and Vancouver Island book t...

buymeacoffee.com

Reply on Twitter 1973599012268941339 Retweet on Twitter 1973599012268941339 0 Like on Twitter 1973599012268941339 0 Twitter 1973599012268941339
robert_desprez avatar; Robert Desprez @robert_desprez ·
27 Sep 1972079492962439576

Image for twitter card

Opinion: Big Tech’s flattery of Trump is getting them nowhere

With the new price tag on H-1B visas, tech companies are learning that currying favour with Trump is a losing game

www.theglobeandmail.com

Reply on Twitter 1972079492962439576 Retweet on Twitter 1972079492962439576 0 Like on Twitter 1972079492962439576 0 Twitter 1972079492962439576
robert_desprez avatar; Robert Desprez @robert_desprez ·
23 Sep 1970576226126541085

Image for twitter card

Is AI the learning tool of the future, or should we be worried about its use in higher education?

Many students are already using AI to conduct research, summarize readings and write essays. On Machines Like Us, ...

www.theglobeandmail.com

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

Recent Blog Posts

  • Using ChatGPT to read smarter
  • ChatGPT: The AI-powered proofreader
  • Four ways Confluence could be better
  • First impressions of MadCap’s purchase of IXIASOFT

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.