Robert Desprez Communications

First Impressions of Adobe RoboHelp 2019

by Leave a Comment

Adobe just released a new ver­sion of FrameMak­er and Robo­Help last month.  If you have used the appli­ca­tion for years, you might be for­giv­en for not even rec­og­niz­ing RoboHelp—it’s been com­plete­ly revamped.

First, for such an old pro­gram (more than 25 years!), Adobe has per­formed an “extreme makeover” when it comes to the user inter­face. It’s clean and mod­ern. It looks like a new application.

RoboHelp 2019 user interface

Adobe has bestowed Robo­Help with a min­i­mal­ist user inter­face. There are not dozens of icons to click like you see in an appli­ca­tion like Microsoft Word. Even though it looks dra­mat­i­cal­ly dif­fer­ent than old­er ver­sions of the pro­gram, I found myself being able to use it right away. How­ev­er, Adobe prob­a­bly rec­og­nized that not every­one wants to learn a new user inter­face so the com­pa­ny is also includ­ing Robo­Help Clas­sic 2019 for those users who pre­fer to work in famil­iar ways.

A Quick Way to Generate Output Files

I like the new way in which you can out­put files.

When you click the Quick Gen­er­ate icon, you can click the out­put you want to gen­er­ate. I like that you can cre­ate out­put files with­out a lot of con­fig­u­ra­tion. I also appre­ci­ate that you can keep work­ing while Robo­Help cre­ates the files in the back­ground. If you want to tweak set­tings for an out­put file, there’s still the Edit button.

Adobe Further Improves RoboHelp’s Search

Robo­Help 2019 builds on some of the improve­ments intro­duced in Robo­Help 2017. Most notably, Robo­Help 2017 includ­ed some wel­come improve­ments by dis­play­ing key­words as users type in the search field. For exam­ple, when I start typ­ing a search query about “con­tact­ing,” Robo­Help starts pro­vid­ing sug­ges­tions on the fly, sim­i­lar to Google’s search engine.

Robo­Help 2019 includes pre­dic­tive search but will also fix users’ typos.  For exam­ple, if I type “HTML5 out­pt,” the HTML5 Help auto­mat­i­cal­ly presents the cor­rect­ed results for me. Giv­en that many users may inad­ver­tent­ly add typos in their search queries, this is a wel­come addition.

RoboHelp 2019 Supports Git, HTML5, and Scalable Vector Graphics

Robo­Help also includes sup­port for Share­Point Online and Git, HTML5, Cas­cad­ing Style Sheets (CSS) 3, and Scal­able Vec­tor Graph­ics (SVG) images. Share­Point and Share­Point Online are not the same thing. With Share­Point Online, you can access inter­nal sites, doc­u­ments, and oth­er infor­ma­tion from anywhere—at the office, at home, or from a mobile device. Git is a ver­sion con­trol sys­tem for track­ing changes in com­put­er files and coor­di­nat­ing work on those files among mul­ti­ple people.

Over­all, I am impressed with the Adobe’s com­mit­ment to over­haul RoboHelp!

 

 

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.

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.

FrameMaker 12 documentation disappoints

by 1 Comment

As FrameMak­er is an author­ing tool made for tech­ni­cal writ­ers, you might think that its help would be exemplary—a show­case of the tool’s capa­bil­i­ties that would inspire oth­er writ­ers to per­form their best work.

Clear­ly, the Adobe tech­ni­cal com­mu­ni­ca­tion group does not share that vision. When I launched FrameMak­er’s help to search for clar­i­fi­ca­tion on its new fea­ture that enables authors to pub­lish to online help (with­out Robo­Help), I felt disappointed.

First, the image qual­i­ty of the screen cap­tures is so poor that I found myself squint­ing to deci­pher them. From the “Mul­ti­chan­nel pub­lish­ing” help top­ic, here are two exam­ples of pix­e­lat­ed graphics:

Publish_icon_croppedGenerate_Multiple_outputs_cropped

In addi­tion, I felt dis­ap­point­ed because the “Mul­ti­chan­nel pub­lish­ing” help top­ic is so long—it is 27 pages when copied to a Word file! A few suggestions:

  • Chunk the con­tent: With a sea of text and a hand­ful of pix­e­lat­ed graph­ics (some of which are mis­aligned), it is over­whelm­ing. I’d split the con­tent into sub-pro­ce­dures to make the con­tent eas­i­er to digest.
  • Reduce the text: Believe it or not, the “Mul­ti­chan­nel pub­lish­ing” help top­ic con­tains almost 7,000 words. When writ­ing con­tent that will be read online, aim to reduce the word count by 50 per­cent. That means if you write a doc­u­ment that is meant to be print­ed and it is 1,000 words, con­sid­er writ­ing 500 words for an online doc­u­ment. With­out a doubt, I’m sure that the con­tent could be more con­cise. For more infor­ma­tion about these guide­lines, see Ruth­less­ly edit when writ­ing for mobile.

I usu­al­ly don’t go out of my way to be crit­i­cal of oth­er tech­ni­cal doc­u­men­ta­tion. If you want to cre­ate online help that is not out­stand­ing, that’s your choice. But per­haps the Adobe writ­ers could at least strive for clear and concise?

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