Robert Desprez Communications

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 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.

Would Faceted Search Assist Your Users?

by 1 Comment

Google’s search engine pars­es through mil­lions of web pages and still deliv­ers amaz­ing search results.

Still, even Google’s search algo­rithm has its lim­its. With more and more web con­tent avail­able every day, you can see why Google offered addi­tion­al fil­ters to help you nar­row your search results. For exam­ple, if you’re look­ing for pic­tures of pump­kins, you can type “pump­kins” in the search field and click Images. Alter­na­tive­ly, if you’re inter­est­ed in the lat­est books about Thanks­giv­ing, you can search for that term and click Books.

Com­pa­nies, such as Dell, have used this technique—called faceted search—for some time.  For exam­ple, 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 pro­vides a lot of ben­e­fits includ­ing the abil­i­ty to be much more spe­cif­ic when look­ing for cer­tain types of content.

Faceted Search and Tech­ni­cal Communication

There has not been a lot of dis­cus­sion about faceted search and tech­ni­cal com­mu­ni­ca­tion. I believe that if your help sys­tem is large (for exam­ple, more than 500 top­ics), a faceted search could help your users search by top­ic type (such as trou­bleshoot­ing con­tent, pro­ce­dures, and con­cep­tu­al mate­r­i­al), train­ing vs. tech­ni­cal com­mu­ni­ca­tion con­tent, HTML ver­sus PDF guides, and so on.

There are, how­ev­er, a few prob­lems with using faceted search with the cur­rent Help Author­ing Tools.

First, most Help Author­ing Tools don’t offer faceted search. So unless you’re using a tool that does offer the func­tion­al­i­ty, you won’t be able to pro­vide it to your users. It’s worth men­tion­ing that Mad­Cap Flare does offer a form of faceted search in its product.

Sec­ond, in my expe­ri­ence, the search in Help Author­ing Tools isn’t great. For many years, Google’s search engine has set the stan­dard for find­ing con­tent online. In con­trast, the out-of-the box search found in a Help Author­ing Tool is mediocre.

Third, I find it’s hard to cus­tomize the search engine in a Help Author­ing Tool. RoboHelp’s search does allow you to tweak con­tent but the last time I looked into it, the search engine is large­ly a black box that isn’t meant to be sig­nif­i­cant­ly customized.

What do you think? Would faceted search help your users? Should it be it avail­able in all Help Author­ing Tools?

HOW WILL TECHNICAL WRITING CHANGE IN THE NEXT 10 YEARS

by 12 Comments

How has tech­ni­cal writ­ing changed in the last 10 years? And how will it be dif­fer­ent in the com­ing years? I start­ed to think about these ques­tions when an old friend asked my opin­ion about how the tools and deliv­er­ables have changed since the late 1990s. She was work­ing as a tech­ni­cal writ­ing man­ag­er back then and is now con­sid­er­ing re-enter­ing the workforce.

I see two notable changes from 10 years ago:

XML author­ing. Of course, one of the main changes in the last 10 years is the wide­spread use of XML when author­ing tech­ni­cal doc­u­ments. Two years ago, Scrip­to­ri­um Pub­lish­ing (http://www.scriptorium.com ) asked more than 600 tech­ni­cal writ­ers whether they write in XML. A major­i­ty of respon­dents were either already writ­ing in XML, imple­ment­ing it, plan­ning to use it, or were at least con­sid­er­ing it. Only 16 per­cent of those sur­veyed didn’t plan to imple­ment it. XML author­ing is not a fad. It’s here to stay.

Improved tools. I start­ed using FrameMak­er 6.0 in the late 1990s. Adobe just released ver­sion 10 in Jan­u­ary. Thank­ful­ly, author­ing tech­ni­cal doc­u­ments has improved sig­nif­i­cant­ly. If you dis­trib­ute PDF doc­u­ments to sub­ject mat­ter experts who make edits in the PDFs, we can now import those edits back into the source files. No more tedious edit­ing. FrameMak­er and Robo­Help can sin­gle source. You can ask sub­ject mat­ter experts to review your files via “the cloud.”

How will tech­ni­cal writ­ing change again in the next 10 years? Here are some edu­cat­ed guesses:

We’ll all be prepar­ing our online help for mobile devices. Smart­phones and tablets are expect­ed to start out­selling com­put­ers in the near future. More and more peo­ple will be using these devices to work and will need tech­ni­cal assis­tance. I expect this is the next “big thing” for us.

Cloud com­put­ing may change how we per­form our jobs. Increas­ing­ly, we may be stor­ing our source files in the cloud, dis­trib­ut­ing tech­ni­cal drafts using the cloud, and even author­ing con­tent using cloud-based soft­ware. See my relat­ed post about cloud com­put­ing.

Social media will change how we com­mu­ni­cate. In my opin­ion, most tech­ni­cal writ­ers are not tak­ing advan­tage of tools like YouTube and Twit­ter. But in the com­ing years, more of us will under­stand how to mar­ry social media and tech­ni­cal doc­u­men­ta­tion. In the April edi­tion of Inter­com mag­a­zine, there’s an inter­est­ing arti­cle called “Under­stand­ing the Help 2.0 Rev­o­lu­tion.” It’s worth check­ing out: www.stc.org. The edi­tion is free too.

These are some of my ini­tial thoughts. How do you think tech­ni­cal writ­ing will change in the next decade?

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