Robert Desprez Communications

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.

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.

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.

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?

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