Robert Desprez Communications

Four Ways Confluence Could Be Better

by Leave a Comment

Years ago, I used Con­flu­ence and then recent­ly used it again at a client site. I liked it when I first used it but feel dis­ap­point­ed that it does not seem to have evolved. Here are four ways that it could be improved.

What is Confluence?

In case you have not used it, Con­flu­ence is a soft­ware prod­uct that makes it easy to col­lab­o­rate across an enterprise.

Import content from PDFs and Word files

On a past project, I import­ed many old­er Word files and PDFs into Confluence.

The Word and PDF files were very dif­fer­ent from the new tem­plate found in Con­flu­ence so I resort­ed to copy­ing con­tent from the source file to the new tem­plate. Even if I first copied con­tent into a text edi­tor (like Notepad), Con­flu­ence fre­quent­ly changed the fonts or font sizes. Re-apply­ing a para­graph style with­in Con­flu­ence to the word or sen­tence did not fix the issue. For­tu­nate­ly, there’s a workaround.

Con­flu­ence Source Edi­tor is a free app that reveals the code on a giv­en page. If all else fails, you can strip out the extra code that is chang­ing the fonts. 


Using Con­flu­ence Source Edi­tor, I can hone in on a cer­tain word and strip out the code that sur­rounds the font. Here is an example:

By strip­ping out the span text, Con­flu­ence then dis­plays the text nor­mal­ly. As some pages can be rid­dled with this extra code, search­ing for and remov­ing it can quick­ly become tedious. 

My sug­ges­tion: Con­flu­ence should address these for­mat­ting issues so that tech­ni­cal authors do not need to fix con­tent this way. At the very least, this Source Edi­tor should be includ­ed in Con­flu­ence with­out hav­ing to search for and install the app.

Search and replace functionality

I worked for a client that rebrand­ed itself, mean­ing that its old name need­ed to be updat­ed on dozens and dozens of Con­flu­ence pages. For author­ing tools like Mad­Cap Flare, the search fea­ture can eas­i­ly comb through mul­ti­ple topics. 

Con­flu­ence includes a search and replace tool but it’s only for page by page. This means that some­one updat­ing the clien­t’s name needs to open the page, going to edit mode, find an instance of the old name, and replace it. This is a very time con­sum­ing process.

Con­flu­ence does offer apps that will per­mit you to search across mul­ti­ple pages with­in a space but they’re not free and you need to research, pay, and install the one that you’d like.

My sug­ges­tion: Atlass­ian, the com­pa­ny that makes Con­flu­ence, needs to include a free search and replace tool as part of its core prod­uct that can scan mul­ti­ple pages with­in a space.

Weak conditional text support

If you’ve used tools like Mad­Cap Flare, you under­stand the pow­er of con­di­tion­al text, which you allows you to sin­gle-source and include or exclude spe­cif­ic sets of infor­ma­tion. You can apply a con­di­tion to a char­ac­ter, word, sen­tence, para­graph, or entire sec­tions of content.

Con­flu­ence includes a form of con­di­tion­al text sup­port but it’s hard­ly robust. Using an app called Scroll Ver­sions, writ­ers can cre­ate dif­fer­ent ver­sions of con­tent and then asso­ciate the con­tent with a “vari­ant.” If you need to cre­ate three dif­fer­ent ver­sions of a para­graph, you can pub­lish three ver­sions using the Scroll Ver­sions app. The main chal­lenge with the app is that it forces users to pick which ver­sion they want to read using a drop­down in Con­flu­ence. Here’s an exam­ple in which a user might select among mul­ti­ple prod­uct versions:

My ver­dict: Although it’s bet­ter than noth­ing, Con­flu­ence’s sup­port is pret­ty weak com­pared to Mad­Cap Flare or oth­er tech­ni­cal writ­ing tools.

No built-in support for variables

In case you haven’t used vari­ables, here’s a def­i­n­i­tion from Mad­Cap’s online help: “Vari­ables are brief, non-for­mat­ted pieces of con­tent (such as the name of your company’s prod­uct or phone num­ber) that can be edit­ed in one place but used in many places…” If you need to update the vari­able, you only need to change it in one place and the change is auto­mat­i­cal­ly made every­where the vari­able appears.

Prod­uct names, cor­po­rate address­es, sup­port phone num­bers all tend to change from time to time. Using vari­ables makes a change super easy. There is an app called Easy Con­flu­ence Vari­ables that may pro­vide some of this func­tion­al­i­ty, although I haven’t had a chance to use it.

I like Con­flu­ence. But if tech­ni­cal writ­ers are going to embrace the tool, Atlass­ian needs to invest more effort in improv­ing it. Besides Con­flu­ence, are there oth­er wikis worth investigating?

Adding Conditions to Microcontent in MadCap Flare 2020

by Leave a Comment

Mad­Cap Flare 2020 adds improve­ments to its micro­con­tent fea­ture by sup­port­ing conditions.

In this blog post, I delve into the enhance­ments and pro­vide step-by-step instruc­tions on how you can mar­ry micro­con­tent with con­di­tions. Flare recent­ly cre­at­ed a post on some of the micro­con­tent improve­ments in the lat­est release of the soft­ware; this blog pro­vides addi­tion­al details.

What is microcontent?

Accord­ing to Flare’s online help, “Micro con­tent is short, con­cise infor­ma­tion that stands alone and is eas­i­ly con­sum­able.” Com­mon ways to use micro­con­tent in Flare include build­ing FAQs, work­ing with chat­bots, and adding micro­con­tent to search results. In this blog post, I explain how to add micro­con­tent in Mad­Cap Flare 2020 to your online help search results.

What does microcontent look like?

If you search for cer­tain terms, such as “con­di­tions” in Mad­Cap Flare’s online help, you see exam­ples of microcontent.

For years, Google has used the same par­a­digm. For exam­ple, type “how to pow­er wash” (I just bought a pow­er wash­er) and the search engine dis­plays a sum­ma­ry of the steps with­out me even hav­ing to click a website.

Add microcontent in Flare

First, I draft­ed a top­ic called “Adding Vari­ables” that includes five steps and two screen cap­tures. I con­di­tion­al­ized the images so they only appear in the topic.

I con­di­tion­al­ized the images with the Top­i­cOn­ly tag (I assume that you know how to con­di­tion­al­ize con­tent in Flare). This top­ic serves as the mas­ter for the microcontent.

To re-use the top­ic as microcontent:

  1. In Flare, click the Con­tent Explorer.
  2. Under Resources, click Micro­Con­tent.
  3. Right-click the Micro­Con­tent fold­er and select New > Micro Con­tent.
  4. In the Add File dia­log box, type a new name for your micro­con­tent in the File Name field and click Add.
  5. In the Micro­con­tent edi­tor, click the Add a phrase icon.
  6. Type a phrase for the micro­con­tent, such as “Vari­ables.” Phras­es are the key­words that you think users will type in the help’s search field when look­ing for a cer­tain topic.
  7. Option­al­ly, you can type alter­nate phras­es for the top­ic (for exam­ple, “Adding Vari­ables,” “Using Vari­ables,” and so on).
  8. Right-click the phrase(s) and select Add Link.
  9. In the Select File dia­log box, link the phrase to a top­ic (I linked my phrase to the Adding Vari­ables top­ic that I recent­ly cre­at­ed) and click OK.
  10. Right-click the phrase you added and select Prop­er­ties.
  11. Click Micro Con­tent Con­di­tions.
  12. In the list of Tags, select Default.TopicOnly and click Exclude. This step excludes the images that I added in the orig­i­nal help top­ic so they do not appear in the microcontent.
  13. Save your project.
  14. Gen­er­ate your help.

View the search results with microcontent

When users type the phrase “Vari­ables” in the search field, they see micro­con­tent that is based on the top­ic but does not dis­play any images as we con­di­tion­al­ized them to not dis­play. We are try­ing to just dis­play crit­i­cal con­tent in a con­cise way. Here’s an example:

Of course, the full top­ic is also avail­able in the help includ­ing the images.

Why is this a welcome improvement?

This enhance­ment is a worth­while devel­op­ment as you can re-use exist­ing top­ics and opti­mize the con­tent so it’s ide­al­ly suit­ed for micro­con­tent. For depart­ments who are already using micro­con­tent, this fea­ture is a wel­come addition.

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.

Editing Tips in Word: Automated Ways to Find Acronyms

by 5 Comments

For all the dis­cus­sion about using con­tent man­age­ment, Dar­win Infor­ma­tion Typ­ing Archi­tec­ture (DITA), and writ­ing for tablets and smart­phones, I find that most clients I work with are still writ­ing at least some con­tent in Microsoft Word.

Most tech­ni­cal writ­ers I know agree that Word has its share of weak­ness­es when author­ing long tech­ni­cal doc­u­ments. Still, many clients grav­i­tate towards it because it’s con­sid­ered “free”—it is almost always installed at a client’s workplace.

For a cur­rent client, I edit long tech­ni­cal Word doc­u­ments that are often rid­dled with acronyms.

I edit the con­tent using some of the stan­dard tech­niques used by edi­tors and tech­ni­cal writ­ers: I com­pare the terms used in the doc­u­ment against the department’s style guide and I use an edit­ing check­list. With­in the last year, I’ve also start­ed using Word’s find fea­ture to scru­ti­nize the document’s acronyms and initialisms.

Finding Acronyms Automatically in Word

In almost every doc­u­ment I read for one client, there is an issue with acronyms not being spelled out or acronyms being incon­sis­tent­ly applied. One auto­mat­ed way to find all the acronyms in a doc­u­ment is to use wild­cards in Word’s Find menu. I first dis­cov­ered this trick on LifeHacker’s web site. I doc­u­ment­ed the fol­low­ing steps using Microsoft Word 2016.

To look for acronyms in a document:

  1. In Word, open a file that you want to edit.
  2. Open the Find win­dow (press Ctrl + F on your keyboard).
  3. In the Nav­i­ga­tion pane, select Advanced Find.

Advanced_Find

  1. Click the More » but­ton.
  2. In the Find what field, type <[A‑Z]{2,}>
  3. Select the Use wild­cards check box.

Find_and_replace_wildcards

  1. Click Read­ing High­light, and then select High­light All.

Find_and_replace_highlight_all

Word high­lights all the ini­tialisms and acronyms in the file. Here is an example:

Acronyms in Word_example

I have found that auto­mat­i­cal­ly search­ing for acronyms has been a tremen­dous time saver and has helped me find count­less incon­sis­ten­cies in client files.

When edit­ing tech­ni­cal doc­u­ments, what tips or tricks have you used to find errors and inconsistencies?

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