Robert Desprez Communications

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.

 

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.

RoboHelp 2015 Provides Users with More Control

by 2 Comments

Adobe Robo­Help (2015 release) allows users to change the con­tent that appears in a HTML5 help project.

For years, users did­n’t have a lot of con­trol over the type of con­tent that would appear in a user guide or online help project. The tech­ni­cal writer made those deci­sions. For exam­ple, if there were three pri­ma­ry audi­ences for a project, the writer would write the con­tent for three audi­ences, tag them with con­di­tion­al text, and then gen­er­ate three sep­a­rate user guides or help projects.

Robo­Help (2015 release), Adobe’s lat­est ver­sion of its help author­ing tool, gives users more con­trol over the type of con­tent they read. For exam­ple, let’s say I have two audi­ences for this online help project: sys­tem admin­is­tra­tors and end users. These 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. By select­ing System_Administrator, the help auto­mat­i­cal­ly dis­plays the con­tent for that audi­ence. Select­ing User will dynam­i­cal­ly change the con­tent for that audience.

System_Admin_Help

For some online help projects, this may pro­vide a lot of ben­e­fits to the writer and the audi­ence. For writ­ers, they won’t need to pro­duce 10 sep­a­rate deliv­er­ables. Instead, they could cre­ate one deliv­er­able and let the audi­ences fil­ter what they want to view. For cer­tain audi­ences, users may appre­ci­ate view­ing and fil­ter­ing all of the con­tent. Writ­ers could include fil­ters on coun­try (for exam­ple, US or Cana­da), audi­ence type (basic users and advanced users), audi­ence title (sup­port staff or project man­agers), and so on.

Although some advanced users may appre­ci­ate this fea­ture, I am not sure it is for every­one. Here are two reser­va­tions I have:

  • Will users even know this fea­ture is avail­able? Users will need to click the Fil­ters tab to see the fea­ture.  Tech­ni­cal writ­ers will prob­a­bly need to high­light and explain the fea­ture as it’s not com­mon on web sites.
  • Will users under­stand what to tog­gle? Tech­ni­cal writ­ers will cre­ate the fil­ters. Will users always under­stand the fil­ters that writ­ers cre­ate? There may be times when users pick the wrong fil­ters, lead­ing to mis­lead­ing and con­fus­ing infor­ma­tion. In addi­tion, when a user selects a fil­ter, there may be no vis­i­ble change in the con­tent for a cer­tain topic—resulting in poten­tial con­fu­sion over what the fea­ture is controlling.

When you’re writ­ing for a tech­ni­cal­ly savvy audi­ence or pow­er users, Robo­Help’s dynam­ic fil­ter­ing may pro­vide a great solu­tion. But novice users may not dis­cov­er the fea­ture or read­i­ly under­stand it.

How RoboHelp’s Search Could be Better

Apart from major user inter­face improve­ments, Robo­Help (2015 release) includes an incre­men­tal improve­ment to the way the search engine works. For more back­ground on this change, see this Tech­whirl review.

As I wrote in an ear­li­er blog entry, RoboHelp’s search could be bet­ter by dis­play­ing key­words in the Search engine field.

When you type spe­cif­ic key­words in Google’s search field, the web site dis­plays a list of sug­gest­ed terms as you type the query. This solu­tion helps users because they may type terms incor­rect­ly or may not even be sure how to phrase their queries in a search field. Google dis­plays sug­gest­ed terms and dis­plays rel­e­vant web sites before I even fin­ish typing.

In Robo­Help (2015 release) , users are still unfor­tu­nate­ly left on their own when it comes to craft­ing a good search.

Anoth­er wel­come addi­tion would be faceted search. Com­pa­nies, such as Dell, have used this tech­nique for some time. On Dell’s web site you can search for a lap­top or desk­top com­put­er. Alter­na­tive­ly, you can use the fil­ters to help you search by prod­uct cat­e­go­ry, proces­sor, screen size, weight, and so on.

For users, this helps stream­line their choic­es. In an online help sys­tem, users could use faceted search to dis­play con­tent by top­ic type (con­cepts, pro­ce­dures, trou­bleshoot­ing con­tent, files with attach­ments or embed­ded movies, and so on).

“Faceted nav­i­ga­tion is arguable the most sig­nif­i­cant search inno­va­tion in the past decade,” write Peter Morville and Jef­fery Cal­len­der in their book Search Pat­terns. “Faceted nav­i­ga­tion is being rapid­ly deployed across an impres­sive­ly wide vari­ety of con­texts and platforms.”

I don’t see why it can­not be deployed in a help author­ing tool.

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.

FrameMaker comes full circle with version 12

by 5 Comments

When I recent­ly start­ed using Adobe’s lat­est ver­sion of FrameMak­er, I felt déjà vu.

Back in the 2000, when I used FrameMak­er 6.0, I wrote con­tent in the soft­ware pro­gram and then con­vert­ed it to Web­Help using Quadralay Cor­po­ra­tion’s Web­Works, which was inte­grat­ed into FrameMak­er at the time. I tagged my con­tent in FrameMak­er using para­graph styles and Web­Works duti­ful­ly con­vert­ed those para­graph styles into HTML code. At the time I worked for a com­pa­ny that want­ed me to cre­ate a help project that took advan­tage of sin­gle sourc­ing. Some­how, I fool­ish­ly accept­ed the task of fig­ur­ing how to cre­ate Web­Help out of FrameMaker.

The project had its share of chal­lenges. The main one was that Web­works’ Java-based ver­sion of the help was not reli­ably appear­ing on users’ screens, osten­si­bly due to issues with the Java Run­time Envi­ron­ment. After con­sid­er­able hair pulling, I dis­cov­ered that Web­Works could out­put a JavaScript ver­sion of the help. Dis­as­ter averted!

In 2005, Adobe acquired Macro­me­dia and with it Robo­Help, its help author­ing tool. A few years lat­er,  Abobe offered its Tech­ni­cal Com­mu­ni­ca­tions Suite, which pro­vid­ed tighter inte­gra­tion between FrameMak­er and Robo­Help. For the first time, you could write con­tent in FrameMak­er and then have con­tent con­vert­ed to help by Robo­Help. Sort of like the FrameMak­er and Web­Works integration.

But not exact­ly. As Robo­Help has been around since 1991, much of its user inter­face looks like a movie from the 1990s. FrameMak­er is no spring chick­en either. Togeth­er, the user is faced with two respect­ed but old and bloat­ed soft­ware pro­grams that are forced to com­mu­ni­cate for the first time. The com­mu­ni­ca­tion worked but it was­n’t ide­al. For exam­ple, when I linked the help files in Robo­Help to the orig­i­nal FrameMak­er files, the updat­ing process was slow and some­times incon­sis­tent. If I made an edit to a FrameMak­er chap­ter, Robo­Help did­n’t always detect the change. And the updat­ing process was­n’t exact­ly sprightly.

Fast for­ward to Adobe’s lat­est ver­sion of FrameMak­er. Ver­sion 12 enables tech­ni­cal writ­ers to cre­ate online help right from FrameMak­er. By not forc­ing users to deal with Robo­Help in the help cre­ation process, I found cre­at­ing Web­Help to be much faster than ear­li­er ver­sions when users need­ed to tog­gle between FrameMak­er and RoboHelp.

FrameMak­er 12 can cre­ate HTML5 help for mobile devices, Web­Help, EPUB files, Kin­dle files, and Microsoft HTML Help.

I have used Robo­Help for years and cre­at­ing online help direct­ly from FrameMak­er does require some par­a­digm shifts (for exam­ple, how table of con­tents are cre­at­ed). But over­all, FrameMak­er 12 makes it faster and sim­pler to cre­ate online help. A wel­come change.

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