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

Adding Conditions to Microcontent in MadCap Flare 2020

May 30, 2020 by RDesprez Leave a Comment

Mad­Cap Flare 2020 adds improve­ments to its micro­con­tent fea­ture by sup­port­ing conditions.

In this blog post, I delve into the enhance­ments and pro­vide step-by-step instruc­tions on how you can mar­ry micro­con­tent with con­di­tions. Flare recent­ly cre­at­ed a post on some of the micro­con­tent improve­ments in the lat­est release of the soft­ware; this blog pro­vides addi­tion­al details.

What is microcontent?

Accord­ing to Flare’s online help, “Micro con­tent is short, con­cise infor­ma­tion that stands alone and is eas­i­ly con­sum­able.” Com­mon ways to use micro­con­tent in Flare include build­ing FAQs, work­ing with chat­bots, and adding micro­con­tent to search results. In this blog post, I explain how to add micro­con­tent in Mad­Cap Flare 2020 to your online help search results.

What does microcontent look like?

If you search for cer­tain terms, such as “con­di­tions” in Mad­Cap Flare’s online help, you see exam­ples of microcontent.

For years, Google has used the same par­a­digm. For exam­ple, type “how to pow­er wash” (I just bought a pow­er wash­er) and the search engine dis­plays a sum­ma­ry of the steps with­out me even hav­ing to click a website.

Add microcontent in Flare

First, I draft­ed a top­ic called “Adding Vari­ables” that includes five steps and two screen cap­tures. I con­di­tion­al­ized the images so they only appear in the topic.

I con­di­tion­al­ized the images with the Top­i­cOn­ly tag (I assume that you know how to con­di­tion­al­ize con­tent in Flare). This top­ic serves as the mas­ter for the microcontent.

To re-use the top­ic as microcontent:

  1. In Flare, click the Con­tent Explorer.
  2. Under Resources, click Micro­Con­tent.
  3. Right-click the Micro­Con­tent fold­er and select New > Micro Con­tent.
  4. In the Add File dia­log box, type a new name for your micro­con­tent in the File Name field and click Add.
  5. In the Micro­con­tent edi­tor, click the Add a phrase icon.
  6. Type a phrase for the micro­con­tent, such as “Vari­ables.” Phras­es are the key­words that you think users will type in the help’s search field when look­ing for a cer­tain topic.
  7. Option­al­ly, you can type alter­nate phras­es for the top­ic (for exam­ple, “Adding Vari­ables,” “Using Vari­ables,” and so on).
  8. Right-click the phrase(s) and select Add Link.
  9. In the Select File dia­log box, link the phrase to a top­ic (I linked my phrase to the Adding Vari­ables top­ic that I recent­ly cre­at­ed) and click OK.
  10. Right-click the phrase you added and select Prop­er­ties.
  11. Click Micro Con­tent Con­di­tions.
  12. In the list of Tags, select Default.TopicOnly and click Exclude. This step excludes the images that I added in the orig­i­nal help top­ic so they do not appear in the microcontent.
  13. Save your project.
  14. Gen­er­ate your help.

View the search results with microcontent

When users type the phrase “Vari­ables” in the search field, they see micro­con­tent that is based on the top­ic but does not dis­play any images as we con­di­tion­al­ized them to not dis­play. We are try­ing to just dis­play crit­i­cal con­tent in a con­cise way. Here’s an example:

Of course, the full top­ic is also avail­able in the help includ­ing the images.

Why is this a welcome improvement?

This enhance­ment is a worth­while devel­op­ment as you can re-use exist­ing top­ics and opti­mize the con­tent so it’s ide­al­ly suit­ed for micro­con­tent. For depart­ments who are already using micro­con­tent, this fea­ture is a wel­come addition.

Filed Under: Help Authoring Tools, Online Writing, Professional Development, Robert Desprez | Vancouver technical writer | Blog, Technology Tagged With: conditions, Madcap Flare, microcontent, single-sourcing

Online Learning Resources for Technical Writers

April 12, 2020 by RDesprez Leave a Comment

Once a year, I com­pile a list of upcom­ing tech­ni­cal writ­ing con­fer­ences in North Amer­i­ca and pub­lish a blog post. With the coro­na virus affect­ing all aspects of our lives, take a look at the Soci­ety for Tech­ni­cal Communication’s online con­fer­ence in May and some online resources to investigate.

STC Virtual Conference (May 17 to 20, 2020)

https://summit.stc.org/

There are some addi­tion­al “in-per­son” tech­ni­cal writ­ing con­fer­ences sched­uled for lat­er in the sum­mer and fall. I expect that these events will be post­poned or re-imag­ined as vir­tu­al events.

MadCap’s webinars

https://www.madcapsoftware.com/resources/recorded-webinars.aspx#flare

Adobe’s webinars

https://meetus.adobeevents.com/technicalcommunication/

Lynda.com courses

In the region I live, the local library offers res­i­dents a free mem­ber­ship to Lynda.com. If you don’t already have a paid mem­ber­ship, you may want to check whether your library pro­vides com­pli­men­ta­ry access. Here is a sam­pling of some cours­es relat­ed to tech­ni­cal writing.

Acro­bat DC Essen­tial Training

GitHub

Work­ing Remotely

Learn­ing Confluence

Instruc­tion­al Design

Get­ting Start­ed in User Experience

List of Good Technical Writing Books

List of books

Podcast on Technical Writing Trends for 2020

Pod­cast

Other Online Resources

While not spe­cif­ic to tech­ni­cal writ­ing, here’s a list of pop­u­lar mas­sive open online cours­es (MOOCs),  online pro­grams with unlim­it­ed par­tic­i­pa­tion and open access via the Inter­net. The list includes a diverse selec­tion of cours­es on arti­fi­cial intel­li­gence, phi­los­o­phy, the chem­istry behind cook­ing, the future of sto­ry­telling, pro­gram­ming, and learn­ing how to learn.

I hope you find this list help­ful. Stay healthy!

Filed Under: Career Development, Professional Development, Robert Desprez | Vancouver technical writer | Blog, Technology, Training Tagged With: massive open online courses, MOOCs, online courses, technical writing, virtual conferences

  • « Previous Page
  • 1
  • 2
  • 3
  • 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.