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!

 

 

Preparing Your Content for Bots? I Am Not.

by 3 Comments

Pre­dic­tions that tech­ni­cal writ­ers will be writ­ing for bots any time soon are overblown. From one upcom­ing tech­ni­cal writ­ing con­fer­ence, here is a sam­pling of some of the upcom­ing presentations:

  • “Con­nect­ing a Chat­bot to Your Tech­ni­cal Content.”
  • “Your Chat­bot Can Lit­er­al­ly Talk Back.”
  • “Prepar­ing for Change in a World of Non-Stop Change: Beyond Chat­bots and Voice.”

Ear­li­er this year, I watched two webi­na­rs on how tech­ni­cal writ­ers can write con­tent for bots. One of the pre­sen­ters acknowl­edged that he felt that writ­ing for bots is in its “infan­cy.” To me, the take­away is this trend isn’t going to take off any­time soon, at least in the tech­ni­cal writ­ing community.

Tech­nolo­gies like bots are tout­ed by indi­vid­u­als who orga­nize tech­ni­cal writ­ing con­fer­ences and con­sul­tants who are more than hap­py to ped­dle clients the “next big thing.” There’s also a lot of fear about arti­fi­cial intel­li­gence and how the robots will usurp all of our jobs. From my per­spec­tive, in my home­town of Van­cou­ver, BC, I find that the adop­tion of new tech­nolo­gies with­in the tech­ni­cal writ­ing com­mu­ni­ty is often slow.

Here is an exam­ple I can share to illus­trate the point. For years, we heard about using the ben­e­fits of struc­tured author­ing using data mod­els for author­ing and pub­lish­ing like Dar­win Infor­ma­tion Typ­ing Archi­tec­ture (DITA). Ten years ago, I was writ­ing in XML using DITA. It seemed like it was going to be the next thing. I was a believ­er. But my unwa­ver­ing faith in all things DITA waned when I real­ized it was a mar­gin­al play­er in a city with a flour­ish­ing high-tech com­mu­ni­ty that employs more than 100,000 peo­ple. More often than not, tech­ni­cal writ­ing depart­ments are writ­ing unstruc­tured con­tent using tools like FrameMak­er, Mad­Cap Flare, wikis, and Microsoft Word.

I am sure that com­pa­nies like Adobe and Mad­Cap will soon intro­duce sup­port for bots. But even when sup­port is intro­duced, I am not expect­ing the change will rev­o­lu­tion­ize life for tech­ni­cal writ­ers in the short term.

Don’t get me wrong: I am not ignor­ing bots. But I don’t feel like I need to jump on the band­wag­on either. There is fre­quent­ly a chasm between what is being pro­mot­ed at con­fer­ences and in webi­na­rs and the real­i­ty of over­worked tech­ni­cal writ­ing depart­ments who may not have time to quick­ly adopt new technologies.

Five Reasons I Like Confluence

by Leave a Comment

For tech­ni­cal writ­ers, there are a lot of rea­sons to like Con­flu­ence, a wiki soft­ware prod­uct that makes it easy to col­lab­o­rate across an enter­prise. Here are five rea­sons I enjoy using it.

Reason #1: Simplified User Interface

Con­flu­ence’s user inter­face is easy to use.  As the list of icons you see is so min­i­mal, you might think that Con­flu­ence isn’t a viable author­ing tool. But the beau­ty of Con­flu­ence is that Alt­lass­ian, the com­pa­ny who devel­ops the soft­ware, has hid­den away some of the more advanced func­tion­al­i­ty.  If you want to extend Confluence’s func­tion­al­i­ty even more, Alt­lass­ian includes more than 800 apps that you can add to the product.

Reason #2: Ease of Re-using Content

Con­flu­ence makes it easy to re-use blocks of con­tent using a two-step process.

First, using Con­flu­ence’s Excerpt macro, you enclose a block of con­tent (for exam­ple, a table) that you’d like to re-use.

The sec­ond step is decid­ing where the re-used con­tent will appear using Con­flu­ence’s Excerpt Include macro. You can have more than one Excerpt Include macro on a page, ref­er­enc­ing con­tent from mul­ti­ple locations.

Here are some more details on using the Excerpt macro: https://confluence.atlassian.com/conf59/excerpt-macro-792499102.html

Here is how to use the Excerpt Include macro: https://confluence.atlassian.com/conf59/excerpt-include-macro-792499101.html

Reason #3: Version Control and Automatic Track Changes

Con­flu­ence auto­mat­i­cal­ly tracks your edits and your Sub­ject Mat­ter Experts’ feed­back. Unlike some appli­ca­tions like Microsoft Word, Con­flu­ence auto­mat­i­cal­ly track changes behind the scenes. At any time, you can review the lat­est ver­sion of the con­tent and com­pare it against an ear­li­er draft.

To view a page’s his­to­ry and its list of edits:

1  Nav­i­gate to a page in Confluence.

2  Click … and click Page His­to­ry.
    [expand  title=“See the fol­low­ing screen cap­ture”][/expand]

Con­flu­ence dis­plays the his­to­ry of the page.
[expand  title=“See the fol­low­ing screen cap­ture”][/expand]
3  On the Page His­to­ry page, you can per­form one or more of the following:

a. Review an ear­li­er ver­sion of the page by click­ing an ear­li­er draft in the Ver­sion column.

b. Restore an old­er ver­sion of the page.

c. Com­pare two ver­sions of the page. Con­flu­ence will show what’s been added, delet­ed, or modified.

The one pro­vi­so about Confluence’s track changes fea­ture is it’s not as detailed as oth­er author­ing tools. For exam­ple, if you have mul­ti­ple Sub­ject Mat­ter Experts review­ing a giv­en page, it’s not obvi­ous who made which edit. In addi­tion, if you antic­i­pate that a page may need to be rewrit­ten, then you’ll be faced with a sea of edits. I find that Con­flu­ence’s Track Changes fea­ture works well if you expect light edits to con­tent you have drafted.

Reason #4: Built-in Support for Adding Flowcharts

Like many oth­ers, I am a big believ­er in includ­ing screen cap­tures or images to help clar­i­fy top­ics I am explaining.

One of the built-in macros is Gliffy, which makes it to easy to include flow­charts and oth­er types of dia­grams online. Here’s an excerpt of a flow­chart that I cre­at­ed in Gliffy.  It was sim­ple to cre­ate and edit.

Reason #5: Improve Your Authoring Experience with Apps

Con­flu­ence is pow­er­ful but you can eas­i­ly extend the prod­uct with more than 800 apps that cus­tomize and extend it using Atlas­sian’s Mar­ket­place.

For tech­ni­cal writ­ers, some use­ful apps include web ana­lyt­ics soft­ware that shows how many peo­ple are vis­it­ing cer­tain pages, how long they spend on each page, key­words that users type in Confluence’s search field, and on. I also cur­rent­ly use a source code app that helps me dis­play a page’s source code when Con­flu­ence does not for­mat con­tent as expect­ed. There are also search-and-replace apps that zero in on key­words and phras­es across mul­ti­ple pages instead of Confluence’s default page-by-page search tool.

Three Challenges of Writing for Mobile

by Leave a Comment

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 are about 1.5 bil­lion peo­ple who are expect­ed to use a tablet by 2019 (source: eMar­keter). Ear­li­er this year, 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. In one study com­plet­ed last year of more than 700 tech­ni­cal com­mu­ni­ca­tion pro­fes­sion­als, only 24 per­cent of tech­ni­cal writ­ers pub­lish con­tent that would be con­sid­ered “mobile ready.”

Although there may be an unde­ni­able user demand for every­thing mobile, prepar­ing con­tent has its share of challenges.

Challenge Number One: Small Screen

In spite of the mod­ern trend towards larg­er-screen phones, what makes mobile phones so con­ve­nient and portable is their small size. Com­pared with desk­top and even lap­top screens, phone screens accom­mo­date a lot less content—see the fol­low­ing illus­tra­tion com­par­ing the sizes of mon­i­tors, tablets, and smartphones.

As a result, mobile users must work hard­er to access the same infor­ma­tion and rely on their short-term mem­o­ry to refer to infor­ma­tion that is not vis­i­ble on the screen.

One way to mit­i­gate users’ small screens is to embrace brevi­ty. One usabil­i­ty con­sul­tant rec­om­mend­ed that if you write 100 words for a print-based doc­u­ment, con­sid­er writ­ing 50 words for the web. For mobile, aim to reduce the word count even more.

Challenge Number Two: Comprehension

Jakob Nielsen, a usabil­i­ty con­sul­tant, has per­formed some stud­ies on user com­pre­hen­sion lev­els on mobile devices.

In a recent study, he found that, on aver­age, com­pre­hen­sion scores were slight­ly high­er when users read the arti­cles on mobile devices. How­ev­er, dif­fi­cult con­tent may cause low­er com­pre­hen­sion on mobile.

The dif­fi­cul­ty of the arti­cles (“easy” or “hard”) was deter­mined by the num­ber of words and the dif­fi­cul­ty of the lan­guage used (accord­ing to the Flesch-Kin­caid read­ing-lev­el for­mu­la). All of the arti­cles were pre­sent­ed as HTML pages cre­at­ed from the same sim­ple design template.

Easy pas­sages were read about as fast on both devices, but hard pas­sages actu­al­ly took longer to read on a mobile device ver­sus a com­put­er.  Easy arti­cles were about 400 words and writ­ten at a Grade 8 lev­el. Hard arti­cles were just under 1,000 arti­cles and at a Grade 12 level.

I would argue that tech­ni­cal com­mu­ni­ca­tion would typ­i­cal­ly fall into the hard category.

The take­away for me is again to sim­pli­fy your con­tent and to get to the point. You’re ask­ing a lot if you write a 1,000-word arti­cle when you know that some users will be read­ing the con­tent on a 5‑inch screen.

Challenge Number Three: Distraction Levels

Smart­phones have rev­o­lu­tion­ized how we live. But as mobile phones are portable, we are more like­ly to be inter­rupt­ed when using them. Nielsen notes that the aver­age user may be using a desk­top for more than 150 sec­onds while the aver­age mobile ses­sion dura­tion is just 72 seconds.

Nielsen rec­om­mends:

  • Allow users to save his­to­ry, as well as to email or share infor­ma­tion with them­selves or others.
  • Pri­or­i­tize what is essen­tial on a page and sim­pli­fy tasks and inter­ac­tions. Because atten­tion is frag­ment­ed, strive to show users what they need as soon as possible.

As users are more and more like­ly to read tech­ni­cal com­mu­ni­ca­tion on a mobile device, it’s an excit­ing time for tech­ni­cal writ­ers to learn new skills and approaches.

Managing Technical Documentation Review Cycles in Confluence

by Leave a Comment

Con­flu­ence makes it easy for tech­ni­cal writ­ers to facil­i­tate reviews of their con­tent. In this blog post, I’ll address some of the dif­fer­ent ways you can solic­it feed­back from Sub­ject Mat­ter Experts using Confluence—by track­ing changes right on the Con­flu­ence page, by upload­ing a Microsoft Office file to Con­flu­ence, or by embed­ding a PDF file inside of a Con­flu­ence page.

What is Confluence?

Con­flu­ence is an online col­lab­o­ra­tion tool that allows peo­ple to cre­ate, share, and dis­cuss files, ideas, min­utes, and tech­ni­cal doc­u­men­ta­tion.  It also pro­vides spaces where con­tent cre­ators can cre­ate and orga­nize con­tent and discussions.

I like Con­flu­ence because it includes a sim­ple user inter­face but also con­tains fea­tures that make it eas­i­er for tech­ni­cal writ­ers to per­form their jobs.

Option 1: Tracking Changes in Confluence

When you write con­tent in Con­flu­ence, then invite one or more Sub­ject Mat­ter Experts to review and make edits to a page, Con­flu­ence auto­mat­i­cal­ly tracks the edits. At any time, you can review the lat­est ver­sion of the con­tent and com­pare it against an ear­li­er draft.

To review a page’s history:

1  Nav­i­gate to a page in Confluence.

2  Click … and click Page His­to­ry.
    [expand  title=“See the fol­low­ing screen cap­ture”][/expand]

Con­flu­ence dis­plays the his­to­ry of the page.
[expand  title=“See the fol­low­ing screen cap­ture”][/expand]

3  On the Page His­to­ry page, you can per­form one or more of the following:

a. Review an ear­li­er ver­sion of the page by click­ing an ear­li­er draft in the Ver­sion column.

b. Restore an old­er ver­sion of the page.

c. Com­pare two ver­sions of the page. Con­flu­ence will show what’s been added, delet­ed, or modified.

The one pro­vi­so about Confluence’s track changes fea­ture is it’s not as detailed as oth­er author­ing tools. For exam­ple, if you have mul­ti­ple Sub­ject Mat­ter Experts review­ing a giv­en page, it’s not obvi­ous who made which edit. In addi­tion, if you antic­i­pate that a page may need to be rewrit­ten, then you’ll be faced with a sea of edits. I find this option works well if you expect light edits to con­tent you have drafted.

Option 2: Adding a Microsoft Office File to Confluence

If you antic­i­pate a lot of changes, use Confluence’s file list fea­ture to add a Microsoft Office file to a page. The ben­e­fit of this approach is that you can use Microsoft Office’s Track Changes fea­ture.  All changes that you make to the Office file are auto­mat­i­cal­ly saved in Confluence.

To track changes by adding a Microsoft Office file to Confluence:

1  Open a Microsoft Office file that you want to upload to Confluence.

2  Make sure that Track Changes are select­ed with­in the Microsoft Office application.

3  In Con­flu­ence, click … beside the Cre­ate button.
    [expand  title=“See the fol­low­ing screen cap­ture”][/expand]

4  In the Cre­ate dia­log box, click Show more.

5 Click File list and click Cre­ate.
    [expand  title=“See the fol­low­ing screen cap­ture”][/expand]

6  In the Cre­ate file list dia­log box, add a name for your file list and click Cre­ate.

7  On the new file list page, upload the Microsoft Office file.

8  Once the file is uploaded, select the expand­able arrow beside the file.
    [expand  title=“See the fol­low­ing screen cap­ture”][/expand]

9  To edit the file, click Edit in Office.
    [expand  title=“See the fol­low­ing screen cap­ture”][/expand]

As the file shown in this exam­ple is a Microsoft Word file, Sub­ject Mat­ter Experts can open the file in Word and make their edits with Track Changes select­ed. After they are fin­ished edit­ing the file, the doc­u­ment is auto­mat­i­cal­ly uploaded to Con­flu­ence. This approach pro­vides Sub­ject Mat­ter Experts with a famil­iar way of working.

Option 3: Adding a PDF to a Confluence Page

Anoth­er way to man­age your reviews is by upload­ing a PDF file to a Con­flu­ence page. When a review­er clicks the PDF, Con­flu­ence opens a sec­ondary win­dow where Sub­ject Mat­ter Experts can review the doc­u­ment page by page. With­in the sec­ondary win­dow, Sub­ject Mat­ter Experts can also add com­ments through the document.

In the fol­low­ing exam­ple, I’ve com­ment­ed on my own doc­u­ment to illus­trate how the fea­ture works.
[expand  title=“See the fol­low­ing screen cap­ture”][/expand]

This may be a good option when you want Sub­ject Mat­ter Experts to review your draft with­out actu­al­ly mak­ing edits to the source con­tent. On the oth­er hand, if get­ting feed­back quick­ly is an issue, this may not be the best option because you then need to incor­po­rate your edits into the source files.

From past expe­ri­ence, I’ve also heard review­ers com­plain about this sec­ondary win­dow as it can be a lit­tle unpre­dictable (for exam­ple, clos­ing unex­pect­ed­ly). It also does not allow users to search for words or phras­es, unlike Adobe Acro­bat Read­er or Adobe Acro­bat Professional.

Con­flu­ence offers mul­ti­ple ways for you to gath­er feed­back from Sub­ject Mat­ter Experts.

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