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.

Which Output to Create: HTML5 or a Mobile App?

by 3 Comments

New Help Author­ing Tools can cre­ate out­put files, such as HTML5 Help, mobile apps, and EPUB files. In this blog post, I am going to touch on what I see are the strengths of HTML5 Help and mobile apps.

First, some def­i­n­i­tions are in order. A mobile appli­ca­tion, most com­mon­ly referred to as an app, is a type of appli­ca­tion soft­ware designed to run on a mobile device, such as a smart­phone or a tablet com­put­er. HTML5 is a markup lan­guage used for struc­tur­ing and pre­sent­ing con­tent on the World Wide Web and is sup­port­ed by all mod­ern browsers. When I refer to HTML5 Help, I am refer­ring to a help project that can be viewed on com­put­ers, tablets, and smartphones.

The fol­low­ing image shows a screen cap­ture of an app for a fic­ti­tious prod­uct called InfoPath.

Mobile_app_example

The next image shows an HTML5 Help project that is dis­played on a computer.

HTML5_example

Strengths of Creating an App

  • The pop­u­lar­i­ty of apps is unde­ni­able. Eighty-five per­cent of users said they pre­fer using apps com­pared to mobile web sites. In addi­tion, users are spend­ing more time using apps—an increase of 21 per­cent in 2015 com­pared to the pre­vi­ous year. Source: Business2Community
  • Ide­al for users who have an inter­mit­tent con­nec­tion to the Inter­net: Once the 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 an 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: An 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.
  • Easy to cre­ate: I’ve cre­at­ed apps in Robo­Help (2015 release) and FrameMak­er (2015 release). Once you have per­formed some con­fig­u­ra­tion steps in both pro­grams, cre­at­ing an app is straight­for­ward.  Note: If you plan to cre­ate iOS appli­ca­tions, you need to pur­chase an Apple devel­op­er account for $99 US per year.

Aside the pre­vi­ous list, there are oth­er issues to con­sid­er, such as how will your app be dis­trib­uted to users so they can view your content.

Strengths of HTML5 Help

  • HTML5 Help auto­mat­i­cal­ly adjusts to the user’s screen: Respon­sive HTML5 Help changes the way the con­tent is pre­sent­ed, based on the device the user is using. For exam­ple, when view­ing con­tent on a PC, a user sees online help with a tra­di­tion­al lay­out while some­one using a smart­phone will see a table of con­tents that is opti­mized for touch. Respon­sive HTML5 Help auto­mat­i­cal­ly adjusts to the user’s screen and adjusts to dynam­ic screen size changes, such as a flip of the ori­en­ta­tion or resiz­ing of the brows­er. As a tech­ni­cal writer, you can author new con­tent or take your lega­cy con­tent and quick­ly out­put it so that it can be viewed on PCs, Macs, and smart­phones and tablets run­ning iOS and Android.

responsive-devices

Source for image: http://techwhirl.com/adobe-technical-communication-suite-2015-release-profile/)

  • Low learn­ing curve: A tech­ni­cal writer cre­ates Respon­sive HTML5 Help in much the same way as tra­di­tion­al help projects, such as Web­Help or Microsoft HTML Help. For any writer that has cre­at­ed online help in the past, cre­at­ing respon­sive HTML5 Help is straight­for­ward. In con­trast, cre­at­ing a mobile app requires some addi­tion­al con­fig­u­ra­tion steps, includ­ing pur­chas­ing an Apple devel­op­er account for iOS applications.
  • Con­sis­tent user expe­ri­ence across plat­forms: When using FrameMak­er or Robo­Help (2015 releas­es), one of the ben­e­fits of respon­sive HTML5 Help is it enables users to expe­ri­ence a sim­i­lar help system—including brand­ing and cor­po­rate col­ors that you can eas­i­ly customize—across devices. Whether your users are run­ning a PC, Mac, smart­phone, or tablet, the respon­sive HTML5 Help pro­vides a con­sis­tent user experience.

 

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.

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?

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