Robert Desprez Communications

List of Online Webinars and North American Conferences for Technical Writers

by 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?

Three Challenges of Writing for Mobile

by Leave a Comment

Now that Android is the lead­ing oper­at­ing sys­tem used to con­nect to the Inter­net, tech­ni­cal writ­ers need to seri­ous­ly look at how their con­tent is being dis­played on smart­phones and tablets.

For years, smart­phone and tablet use has sky­rock­et­ed.  In 2016, the num­ber of smart­phone users was expect­ed to sur­pass 2 bil­lion (source: eMar­keter). Sim­i­lar­ly, there are about 1.5 bil­lion peo­ple who are expect­ed to use a tablet by 2019 (source: eMar­keter). Ear­li­er this year, Android has edged out Win­dows as the num­ber one oper­at­ing sys­tem used to access the Inter­net.

Mean­while, tech­ni­cal writ­ers appear to be slow to embrace mobile. In one study com­plet­ed last year of more than 700 tech­ni­cal com­mu­ni­ca­tion pro­fes­sion­als, only 24 per­cent of tech­ni­cal writ­ers pub­lish con­tent that would be con­sid­ered “mobile ready.”

Although there may be an unde­ni­able user demand for every­thing mobile, prepar­ing con­tent has its share of challenges.

Challenge Number One: Small Screen

In spite of the mod­ern trend towards larg­er-screen phones, what makes mobile phones so con­ve­nient and portable is their small size. Com­pared with desk­top and even lap­top screens, phone screens accom­mo­date a lot less content—see the fol­low­ing illus­tra­tion com­par­ing the sizes of mon­i­tors, tablets, and smartphones.

As a result, mobile users must work hard­er to access the same infor­ma­tion and rely on their short-term mem­o­ry to refer to infor­ma­tion that is not vis­i­ble on the screen.

One way to mit­i­gate users’ small screens is to embrace brevi­ty. One usabil­i­ty con­sul­tant rec­om­mend­ed that if you write 100 words for a print-based doc­u­ment, con­sid­er writ­ing 50 words for the web. For mobile, aim to reduce the word count even more.

Challenge Number Two: Comprehension

Jakob Nielsen, a usabil­i­ty con­sul­tant, has per­formed some stud­ies on user com­pre­hen­sion lev­els on mobile devices.

In a recent study, he found that, on aver­age, com­pre­hen­sion scores were slight­ly high­er when users read the arti­cles on mobile devices. How­ev­er, dif­fi­cult con­tent may cause low­er com­pre­hen­sion on mobile.

The dif­fi­cul­ty of the arti­cles (“easy” or “hard”) was deter­mined by the num­ber of words and the dif­fi­cul­ty of the lan­guage used (accord­ing to the Flesch-Kin­caid read­ing-lev­el for­mu­la). All of the arti­cles were pre­sent­ed as HTML pages cre­at­ed from the same sim­ple design template.

Easy pas­sages were read about as fast on both devices, but hard pas­sages actu­al­ly took longer to read on a mobile device ver­sus a com­put­er.  Easy arti­cles were about 400 words and writ­ten at a Grade 8 lev­el. Hard arti­cles were just under 1,000 arti­cles and at a Grade 12 level.

I would argue that tech­ni­cal com­mu­ni­ca­tion would typ­i­cal­ly fall into the hard category.

The take­away for me is again to sim­pli­fy your con­tent and to get to the point. You’re ask­ing a lot if you write a 1,000-word arti­cle when you know that some users will be read­ing the con­tent on a 5‑inch screen.

Challenge Number Three: Distraction Levels

Smart­phones have rev­o­lu­tion­ized how we live. But as mobile phones are portable, we are more like­ly to be inter­rupt­ed when using them. Nielsen notes that the aver­age user may be using a desk­top for more than 150 sec­onds while the aver­age mobile ses­sion dura­tion is just 72 seconds.

Nielsen rec­om­mends:

  • Allow users to save his­to­ry, as well as to email or share infor­ma­tion with them­selves or others.
  • Pri­or­i­tize what is essen­tial on a page and sim­pli­fy tasks and inter­ac­tions. Because atten­tion is frag­ment­ed, strive to show users what they need as soon as possible.

As users are more and more like­ly to read tech­ni­cal com­mu­ni­ca­tion on a mobile device, it’s an excit­ing time for tech­ni­cal writ­ers to learn new skills and approaches.

Editing Tips in Word: Automated Ways to Find Acronyms

by 5 Comments

For all the dis­cus­sion about using con­tent man­age­ment, Dar­win Infor­ma­tion Typ­ing Archi­tec­ture (DITA), and writ­ing for tablets and smart­phones, I find that most clients I work with are still writ­ing at least some con­tent in Microsoft Word.

Most tech­ni­cal writ­ers I know agree that Word has its share of weak­ness­es when author­ing long tech­ni­cal doc­u­ments. Still, many clients grav­i­tate towards it because it’s con­sid­ered “free”—it is almost always installed at a client’s workplace.

For a cur­rent client, I edit long tech­ni­cal Word doc­u­ments that are often rid­dled with acronyms.

I edit the con­tent using some of the stan­dard tech­niques used by edi­tors and tech­ni­cal writ­ers: I com­pare the terms used in the doc­u­ment against the department’s style guide and I use an edit­ing check­list. With­in the last year, I’ve also start­ed using Word’s find fea­ture to scru­ti­nize the document’s acronyms and initialisms.

Finding Acronyms Automatically in Word

In almost every doc­u­ment I read for one client, there is an issue with acronyms not being spelled out or acronyms being incon­sis­tent­ly applied. One auto­mat­ed way to find all the acronyms in a doc­u­ment is to use wild­cards in Word’s Find menu. I first dis­cov­ered this trick on LifeHacker’s web site. I doc­u­ment­ed the fol­low­ing steps using Microsoft Word 2016.

To look for acronyms in a document:

  1. In Word, open a file that you want to edit.
  2. Open the Find win­dow (press Ctrl + F on your keyboard).
  3. In the Nav­i­ga­tion pane, select Advanced Find.

Advanced_Find

  1. Click the More » but­ton.
  2. In the Find what field, type <[A‑Z]{2,}>
  3. Select the Use wild­cards check box.

Find_and_replace_wildcards

  1. Click Read­ing High­light, and then select High­light All.

Find_and_replace_highlight_all

Word high­lights all the ini­tialisms and acronyms in the file. Here is an example:

Acronyms in Word_example

I have found that auto­mat­i­cal­ly search­ing for acronyms has been a tremen­dous time saver and has helped me find count­less incon­sis­ten­cies in client files.

When edit­ing tech­ni­cal doc­u­ments, what tips or tricks have you used to find errors and inconsistencies?

Embedding Fonts in EPUB Files

by Leave a Comment

New­er Help Author­ing Tools such as Robo­Help (2015 release) and Mad­Cap Flare make it eas­i­er to embed fonts in EPUB files. This blog entry pro­vides step-by-step instruc­tions on how to embed fonts in Robo­Help (2015 release).

Some Basics

An EPUB doc­u­ment is a zip file with the .epub exten­sion. EPUB files can be read using e‑reader soft­ware on many devices includ­ing the iPad, iPhone, PCs, and smart­phones run­ning on Android. There are many types of e‑reader pro­grams. For this blog post, I down­loaded and installed Adobe Dig­i­tal Edi­tions on my computer.

For tech­ni­cal writ­ers, I believe EPUB files are one of the tech­nolo­gies to watch. The iBooks book­store sells its e‑books in an EPUB file for­mat. With tablets and smart­phones out­selling PCs, users are increas­ingly read­ing content—including tech­ni­cal communications—on these devices. Help Author­ing Tools also make it easy to cre­ate EPUB files.

One of the key advan­tages of an EPUB file is its abil­i­ty to reflow on dif­fer­ent devices.  The fol­low­ing image shows how an EPUB file appears on an iPad:

EPUB file shown on an iPad

The next screen shot shows how the same file appears on an iPhone:

EPUB on an iPhone

In con­trast, a PDF file may look beau­ti­ful on your 24-inch mon­i­tor at home but is dif­fi­cult to read on your smartphone.

Why Embed Fonts?

There may be times when you want to embed a font into your EPUB file to give a doc­u­ment a cus­tom look. If you are going to add cus­tom fonts to an EPUB file, you need to embed the font.  Oth­er­wise, some—or all—users will see the doc­u­ment dif­fer­ent­ly than you envisioned.

The fol­low­ing screen shot shows how an embed­ded font (called “Quin­tes­sen­tial”) appears on an iPad. With­out embed­ding the font, the user may see it in Ari­al (or anoth­er font), due to a font substitution.

embedding fonts

Embedding Fonts in the Past

In the past, if you want­ed to embed a font in a EPUB file, you first need­ed to down­load a font from a site such as Google Web­Fonts, unzip the fold­ers inside an EPUB file, add the font to the cor­rect fold­er, and change your Cas­cad­ing Style Sheet (CSS) so that fonts would appear prop­er­ly. The process was not dif­fi­cult but sus­cep­ti­ble to errors. If you did not down­load the font to the cor­rect fold­er in your EPUB project, the font would not appear prop­er­ly. If you made a mis­take typ­ing some code into a CSS file—even for­get­ting to add a “;”—your font would not be prop­er­ly embedded.

Embedding Fonts is Much Easier Now

Thank­ful­ly, in new­er Help Author­ing Tools, embed­ding fonts is much easier.

Downloading the Font

To down­load the font:

  1. Vis­it a site such as Google WebFonts.
  2. Find a font that you like.
  3. Down­load and install it on your com­put­er that is run­ning Robo­Help (2015).

Adding a Custom Font to your EPUB File

In your Robo­Help (2015) project, make a deci­sion where you want to use cus­tom fonts. For instance, you may decide that all Nor­mal text should use a cus­tom font.

To add a cus­tom font:

  1. Select the text in which you want to apply a cus­tom font.
  2. Select the Edit menu.
  3. In the rib­bon, select Edit Stylesheet.
  4. In the For­mat­ting sec­tion, select the font you want to use from the Font drop­down list. Click OK.

Style_dialog_box_font

To embed a font in Robo­Help (2015 release):

  1. In the Out­put menu, click eBook.
  2. In the eBook Set­tings dia­log box, select Con­tent.
  3. Select the Embed Fonts check box.

Embedding_fonts_RoboHelp

  1. Click Man­age.
  2. In the Embed Fonts dia­log box, select a font that you want to embed, click the Add but­ton, and click OK.

embed fonts_dialog

  1. Click Save and Gen­er­ate.
  2. In the dia­log box that appears, click View Result.

The e‑reader soft­ware (in this case, Adobe Dig­i­tal Edi­tions) dis­plays the embed­ded font.

Embedded_font_EPUB

New ver­sions of Help Author­ing Tools have made embed­ding fonts in EPUB files much simpler.

Three Ways to Customize a Mobile App

by Leave a Comment

This blog entry explains some ways that you can cus­tomize the look and feel of your mobile app using Robo­Help (2015 release). This blog post focus­es on cre­at­ing a mobile app that runs on Android devices.

Displaying or Hiding your Table of Contents, Index, Glossary, or Filters

In Robo­Help (2015 release), you can cre­ate a table of con­tents and index if you feel it makes it eas­i­er for users to nav­i­gate your help sys­tem. In my expe­ri­ence, cre­at­ing an index for a client is increas­ing­ly rare, as users appear to rely more and more on search to find the answers they need. You may also want to include a Glos­sary if your mobile app con­tains many terms that need to be explained.

Fil­ters per­mit users to select the type of con­tent that appears in an online help sys­tem. For exam­ple, let’s say I have two audi­ences for an online help project: sys­tem admin­is­tra­tors and end users. The read­ers can con­trol the type of con­tent that dis­plays in the help by click­ing the Fil­ter but­ton and select­ing the check box­es for the dif­fer­ent audi­ences. Sys­tem admin­is­tra­tors, for instance, can select the fil­ter so that they only see the con­tent that per­tains to them. For more infor­ma­tion about the fil­ter fea­ture, see Robo­Help 2015 pro­vides users with more con­trol.

To hide or dis­play a table of con­tents, index, glos­sary, or filters:

  1. In the Out­put menu, click Mobile App.

List_of_outputs

  1. In the Mobile App Set­tings dia­log box, select Gen­er­al.
  2. Click Cus­tomize Select­ed Lay­out.
  3. In the Lay­out Cus­tomiza­tion dia­log box, select Basic settings in the Lay­out Com­po­nents list.
  4. In the Prop­er­ties list, select whether you want to show or hide your mobile app’s table of con­tents, index, glos­sary or filters:

a) For the table of con­tents, index, glos­sary, or fil­ter, select true or false from the adja­cent drop­down list.

Layout_Customization

  1. Click Save.

Adding a Logo

If you add a logo, it appears in the top-left cor­ner of the mobile app. I cre­at­ed a sim­ple help app for a fic­ti­tious prod­uct called InfoPath.

logo in outputted app

To add a logo to the mobile app:

  1. In the Out­put menu, click Mobile App.

List_of_outputs

  1. In the Mobile App Set­tings dia­log box, select Gen­er­al.
  2. Click Cus­tomize Select­ed Layout.
  3. In the Lay­out Cus­tomiza­tion dia­log box, select Head­er in the Lay­out Com­po­nents list.
  4. In the Prop­er­ties list, click … beside Logo to select an image.

Logo_latest

  1. In the Open dia­log box, nav­i­gate to a PNG image that you want to use for the logo and click Open. It’s best to use a square shaped logo. I used an image that was 72 by 72 pixels.
  2. Click Save.

Adding a Mobile App Icon

A mobile app icon is the image that appears when the app is installed on an Android smart­phone or tablet. The fol­low­ing image shows an example:

Icon_example

To add a mobile app icon:

  1. In the Out­put menu, click Mobile App.

List_of_outputs

  1. In the Mobile App Set­tings dia­log box, select Appli­ca­tion Details.
  2. In the Icon field,  click the browse icon and nav­i­gate to a PNG file. I used a 72  by 72 pix­els file—the same image that I used for the logo.  For more infor­mation about the rec­om­mend­ed icon sizes, see GitHub’s web page.

Mobile_App_Settings

  1. Click Save and Gen­er­ate.

Robo­Help (2015 release) gen­er­ates the mobile app.

  1. Click View Result in the Result: Mobile App out­put has been gen­er­ated suc­cess­fully dia­log box.

Downloading the Mobile App

The next step explains how to get the mobile app loaded onto your Android tablet or smartphone.

To down­load the mobile app to your Android phone:

  1. In your phone’s or tablet’s brows­er, type the URL that appears in the Mobile App Out­put dia­log box.
    Mobile_App_Output dialog box
  2. Alter­na­tive­ly, you can down­load the mobile app using a QR Reader.

a) Down­load a QR read­er to your Android phone. I down­loaded the QR Code Read­er from Google Play.

b) Using the QR read­er, scan the QR code in the Mobile App Out­put dia­log box.

The mobile app down­loads to your tablet or smartphone.

Viewing the Mobile App

Once the mobile app has been down­loaded and installed on your com­put­er, tap the mobile app you cre­at­ed. I haven’t attempt­ed to doc­u­ment down­load­ing and installing the app, due to the dif­fer­ent ver­sions of Android.

 

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