Robert Desprez Communications

FrameMaker 2017 Delivers New HTML5 Templates

by Leave a Comment

FrameMak­er 2017 deliv­ers online help for mobile devices and includes two new respon­sive HTML5 help templates.

For years, FrameMak­er has been a lead­ing tool to cre­ate long and com­plex doc­u­ments. But if you required an online help sys­tem from FrameMak­er, you need­ed anoth­er soft­ware prod­uct, whether it was Web­Works (in the late 1990s) or Robo­Help (after 2005). A few years ago, Adobe changed all that, enabling FrameMak­er to cre­ate web- and mobile-friend­ly con­tent direct­ly from the soft­ware product.

FrameMak­er 2017 pro­vides two new respon­sive HTML5 tem­plates. Here’s an exam­ple of a help sys­tem for a fic­ti­tious prod­uct using the new “Indi­go” template:

Here’s the out­put using the “Ocean” tem­plate that comes with FrameMak­er 2017: 

FrameMaker’s Improved Search

In a world where users have embraced search, FrameMak­er 2017 includes some improve­ments by dis­play­ing key­words as you type in the search field. For exam­ple, when I start typ­ing a search query about “error mes­sages,” the respon­sive HTML5 starts pro­vid­ing sug­ges­tions on the fly, sim­i­lar to Google’s search engine. This “pre­dic­tive search” is avail­able in the respon­sive HTML5 help that is shipped with the lat­est ver­sion of FrameMaker.

Accord­ing to usabil­i­ty con­sul­tant Jakob Nielsen, users love search for two reasons:

  • Search lets users “con­trol their own des­tiny” and assert inde­pen­dence from com­pa­nies’ attempts to direct vis­i­tors on web sites.
  • Search is also users’ “escape hatch when they are stuck in nav­i­ga­tion.” When they can’t find a rea­son­able place to go next, they often turn to the site’s search function.

Giv­en that users love using search, it’s some­what sur­pris­ing that Nielsen found that they are often not very savvy when it comes to for­mu­lat­ing search queries.  He writes: “Typ­i­cal users are very poor at query refor­mu­la­tion: If they don’t get good results on the first try, lat­er search attempts rarely suc­ceed. In fact, they often give up.”

As cus­tomers increas­ing­ly focus on search to find rel­e­vant con­tent, the new search engine that is shipped with FrameMak­er 2017 is a wel­come addi­tion that should improve the user experience.

Why are Technical Writers Slow to Embrace Mobile?

by 3 Comments

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 were about 1 bil­lion peo­ple world­wide in 2015 who used a tablet at least month­ly (source: eMar­keter). In the last few weeks, 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. The Con­tent Wran­gler web site com­plet­ed a study last year of more than 700 tech­ni­cal com­mu­ni­ca­tion pro­fes­sion­als. The sur­vey found that 91 per­cent of firms sur­veyed pub­lish con­tent to the web. But only 24 per­cent of tech­ni­cal writ­ers pub­lish con­tent that would be con­sid­ered “mobile ready.”

Sur­prised? I am not.  Although tech­ni­cal com­mu­ni­ca­tions con­fer­ences are brim­ming with ideas about get­ting your con­tent ready for mobile, we are not embrac­ing the idea. You can­not blame the author­ing tools either. In the last few years, Help Author­ing Tools have pro­vid­ed new and for­ward-think­ing fea­tures that make it easy to cre­ate Respon­sive HTML5 and EPUB files. With Robo­Help, you can even cre­ate a mobile app that con­tains online help (I explain the basics of cre­at­ing a mobile app in a sep­a­rate blog post). In addi­tion, these tools are rel­a­tive­ly inex­pen­sive: you can pur­chase some of them on a month­ly sub­scrip­tion basis.

So why are more than 75 per­cent of tech­ni­cal writ­ers not writ­ing con­tent that is mobile ready? Here’s one guess: for all the talk about Dar­win Infor­ma­tion Typ­ing Archi­tec­ture (DITA), writ­ing con­tent for mobile, con­tent man­age­ment, and social media, there are still a lot of com­pa­nies that are using old approach­es and old tools, such as Microsoft Word, to write tech­ni­cal com­mu­ni­ca­tions. The Con­tent Wran­gler study appears to sup­port this the­o­ry with 49% of com­pa­nies sur­veyed still craft­ing print deliverables—just like it was done 20 years ago.

What do you think?

Creating a Mobile App for Android Devices

by 6 Comments

Robo­Help (2015 release) makes it easy for tech­ni­cal writ­ers to gen­er­ate a mobile app for smart­phones and tablets run­ning iOS and Android.

You may con­sid­er cre­at­ing a mobile app for the fol­low­ing reasons:

  • Your users have an inter­mit­tent con­nec­tion to the Inter­net: Once the mobile app is installed on a smart­phone or tablet, it no longer requires a wire­less or mobile con­nec­tion to view the con­tent. In con­trast, HTML5 help sys­tems require a brows­er, which usu­al­ly needs an Inter­net con­nec­tion to view the con­tent (although some browsers, such as Google Chrome, can run in offline mode).
  • Speed: Users will get the answers they need faster using a mobile app ver­sus launch­ing a brows­er, nav­i­gat­ing to your help page, and wait­ing for the con­tent to appear.
  • High­er vis­i­bil­i­ty: A mobile app is installed on a user’s smart­phone or tablet, mak­ing it easy to locate and launch. In con­trast, an online help sys­tem is typ­i­cal­ly includ­ed in a soft­ware pack­age and may not be easy to find or open.

This pro­ce­dure explains how to use Robo­Help (2015 release) to cre­ate a mobile app for an Android phone or tablet. It also assumes you have some famil­iar­i­ty with cre­at­ing online help sys­tems and under­stand the basics of down­load­ing and installing mobile apps on Android smart­phones and tablets.

Creating a Mobile App

  1. In Robo­Help (2015 release), open a project that you want to con­vert to a mobile app.
  2. From the Out­put menu, click Mobile App.

List_of_outputs

  1. In the MobileApp Set­tings dia­log box, click Appli­ca­tion Details.
  2. In the Mobile App Details sec­tion, fill out the fol­low­ing fields:

a) Pack­age: A name that will unique­ly iden­ti­fy the mobile app such as “com.adobe.myapp.” This name is used by Phone­Gap to iden­ti­fy the appli­ca­tion. Phone­Gap is a mobile devel­op­ment frame­work to cre­ate mobile apps on iOS, Android, and Win­dows Phone. Phone­Gap’s web site is https://build.phonegap.com/

b) Ver­sion: The Phone­Gap ver­sion num­ber for the mobile app (for exam­ple, ver­sion 0.01).

c) Ver­sion­Code (Android): The Android ver­sion num­ber for the mobile app. If you upload your app to Android’s Google Play (the offi­cial app store for Android smart­phones and tablets), a user will be noti­fied of updates to your app every time you update the ver­sion number.

d) Title: The title of the appli­ca­tion that will dis­play on a mobile device.

e) Icon: The icon of the appli­ca­tion that will dis­play on a mobile device. For more infor­ma­tion about the rec­om­mend­ed icon sizes, see GitHub’s web page.

f) Splash Screen: The splash screen that will dis­play when the mobile app is opened on a mobile device. For more infor­ma­tion about the rec­om­mend­ed splash screen sizes, see GitHub’s web page.

  1. In the PhoneGap/Adobe Cre­den­tial sec­tion, type your Adobe User Name and Pass­word. As Phone­Gap is owned by Adobe, you can use the same web site cre­den­tials that you use when down­load­ing any Adobe prod­uct. After typ­ing your cre­den­tials, click Test Con­nec­tion to con­firm the Phone­Gap con­nec­tion. I found that this dia­log box didn’t rec­og­nize my cre­den­tials until I first logged on to PhoneGap’s web site.
  2. In the Plat­form sec­tion, select the Android check box.

Mobile_App_Settings

  1. In the Mobile App Set­tings dia­log box, click Con­tent.

a) In the Table of Con­tents drop­down list, select the table of con­tents you want to use for the mobile app.

b) If you cre­at­ed an index, in the Index drop­down list, select the index you want to use.

c) If you cre­at­ed a glos­sary, in the Glos­sary drop­down list, select the glos­sary you want to use.

d) 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­at­ed suc­cess­ful­ly 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.

I cre­at­ed a sim­ple help app for a fic­ti­tious prod­uct called InfoPath. I cre­at­ed the icon in Snag­it and then import­ed the image into Robo­Help (2015 release). Here’s a screen shot of the down­loaded app on my phone:

2015-08-20 20.11.20

Here is an exam­ple of how the mobile app dis­plays when I open it.

2015-08-17 21.38.43

As an expe­ri­enced tech­ni­cal writer, I found cre­at­ing and down­load­ing a mobile app to be fast and straightforward.

Do We Rely Too Much on Technology?

by Leave a Comment

Does soft­ware automa­tion improve or ham­per your life?

Most peo­ple embrace the idea of tech­nol­o­gy. How many peo­ple real­ly would rel­ish writ­ing a let­ter or even an email with­out spell check? Or endure a rush-hour dri­ve into a for­eign city with­out a GPS system?

Nicholas Carr, author of The Glass Cage, argues that for all of technology’s ben­e­fits, it has its share of per­ils. When peo­ple use com­put­ers, they often fall vic­tim to a pair of cog­ni­tive ailments—automation com­pla­cen­cy and automa­tion bias.

Technology Can Harm our Careers and Threaten Lives

Automa­tion com­pla­cen­cy lulls us into a false sense of secu­ri­ty. Carr writes: “We become so con­fi­dent that the machine will work flaw­less­ly, han­dling any chal­lenge that may arise, that we allow our atten­tion to drift. We dis­en­gage from our work, or at least the part of it that the soft­ware is han­dling, and as a result may miss sig­nals that some­thing is amiss.” Any­one who uses a word proces­sor will have expe­ri­enced this: per­haps the spell check doesn’t catch an embar­rass­ing error. Or a foot­er does not dis­play the cor­rect information.

Automa­tion bias occurs when peo­ple give too much cre­dence to the infor­ma­tion dis­played by a com­put­er. Even when the infor­ma­tion is wrong or mis­lead­ing, peo­ple may still believe it. One alarm­ing exam­ple is a dri­ver of a school bus who mis­tak­en­ly rammed into a con­crete bridge in Seat­tle, injur­ing 21 stu­dents. The dri­ver told police that he had been fol­low­ing the GPS instruc­tions and “did not see” signs and flash­ing lights warn­ing of the impend­ing bridge.

Soft­ware automa­tion is every­where in our soci­ety. Accoun­tants use deci­sion-sup­port soft­ware in cor­po­rate audits. The soft­ware expe­dites the work but “there are trou­bling signs that as the soft­ware becomes more capa­ble the accoun­tants become less so,” writes Carr. One study, con­duct­ed by a group of Aus­tralian pro­fes­sors, exam­ined the effect of the soft­ware sys­tems used by three account­ing firms. Those accoun­tants who had to make more of the deci­sions them­selves had “a sig­nif­i­cant­ly stronger under­stand­ing of dif­fer­ent forms of risk” than the oth­er accoun­tants who relied on the soft­ware. “The decline in learn­ing asso­ci­at­ed with advanced soft­ware affect­ed even vet­er­an audi­tors,” writes Carr.

A ten­den­cy to be increas­ing­ly reliant on soft­ware is not unique to accoun­tants. Finan­cial pro­fes­sion­als, lawyers, doc­tors, human resource pro­fes­sion­als, pilots all rely on soft­ware to com­plete aspects of their jobs. The book con­tains many exam­ples of how these well-edu­cat­ed pro­fes­sion­als become over­ly reliant on tech­nol­o­gy and make mistakes—sometimes life-threat­en­ing ones.

Online Information May Weaken our Memory

In the devel­oped world, most of can­not imag­ine our lives with­out an Inter­net con­nec­tion and a search engine.

When you type in a search query using Google, the search engine does a great job of fig­ur­ing out what you want. It cor­rects your spelling. It sug­gests search terms. It even antic­i­pates your needs based on who you are and the terms you have used in the past. Over time, you might think that users are learn­ing from Google’s sug­ges­tions so that they are more savvy when typ­ing search terms.

The oppo­site is true. A series of exper­i­ments in Sci­ence mag­a­zine show that all the avail­able online infor­ma­tion weak­ens our mem­o­ry for facts. Why remem­ber fac­tu­al con­tent when a search engine will do it for you? The researchers con­clud­ed: “Since search engines are con­tin­u­al­ly avail­able to us, we may often be in a state of not feel­ing we need to encode the infor­ma­tion internally.”

Amit Sing­hal, Google’s lead engi­neer, notes that the bet­ter Google’s search engine becomes, the lazier we are with our typ­ing and queries.

Most of us wouldn’t accept a world with­out soft­ware, whether it’s a GPS, bank­ing soft­ware, or a smart­phone. Tech­nol­o­gy has rev­o­lu­tion­ized our lives in many pos­i­tive ways. But for those of us enam­oured with tech­nol­o­gy, Carr’s book is a a cau­tion­ary tale—don’t let your guard down too much when using it.

List of upcoming
technical communications conferences

by 6 Comments

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

Intel­li­gent Con­tent Con­fer­ence, March 23–25, San Francisco
http://www.intelligentcontentconference.com/

Mad­World 2015 World­wide Learn­ing Con­fer­ence, April 12–14, San Diego
http://www.madcapsoftware.com/events/madworld/

Writ­er­sUA User Assis­tance Boot Camp, April 15–17, Seattle
http://west.writersua.com/

Con­tent Man­age­ment Strategies/DITA North Amer­i­ca, April 20–22, Chicago
http://www.cm-strategies.com/2015/index.htm

IA Sum­mit, April 22–26, Minneapolis
http://www.iasummit.org/

Write the Docs 2015, May 17–19, Portland
http://www.writethedocs.org/conf/na/2015/

STC annu­al con­fer­ence, June 21–24, Columbus
http://summit.stc.org/

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

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

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