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?

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 to use illustrations to make your
technical docs clearer

by 3 Comments

Images can be a suc­cinct and effec­tive way to con­vey a mes­sage. Yet I don’t see many illus­tra­tions being used in tech­ni­cal com­mu­ni­ca­tions. Many writers—including me—don’t think their strength is illustrating.

Dan Roam, in his book The Back of the Nap­kin, argues that one does­n’t have to be a gift­ed artist or use Adobe Illus­tra­tor or Microsoft Pow­er­Point to cre­ate effec­tive images. Draw­ings can be as sim­ple as hand-drawn pic­tures, he says. Indeed, his book is brim­ming  with draw­ings that resem­ble doo­dles. One of my favorite things about Roam’s book is that he offers a frame­work that helps read­ers think about how to approach illustrating.

Here are some of the draw­ings he discusses:

  • Por­traits: To explain a con­cept that address­es the “who” or “what,” Roam rec­om­mends using a qual­i­ta­tive dia­gram. For exam­ple, many peo­ple strug­gle with under­stand­ing the term “meta­da­ta.” You could try to define it (such as “it’s data about data.”) But that def­i­n­i­tion often leaves peo­ple still scratch­ing their heads. An alter­na­tive solution—you could draw it.

Example of metadata

In short, meta­da­ta pro­vides more details about a doc­u­ment, such as who wrote the file, when the per­son wrote it, the point of the doc­u­ment, and so on.

  •  Charts: If you’re try­ing to com­mu­ni­cate a quan­ti­ty, writ­ing about it may suf­fice. But if you’re per­form­ing a com­par­i­son, a pie chart or bar chart is the best choice. Here’s a fic­ti­tious example:

example_chart

  • Time­lines: To explain a process or work­flow, you could try explain­ing each step. Anoth­er way to accom­plish the same thing is by using a sim­ple work­flow dia­gram, which explains “when” some­thing hap­pens in a process. For work­flows, I fre­quent­ly use Microsoft Office’s Smar­tArt fea­ture. Here’s a sam­ple work­flow I cre­at­ed that con­veys a com­mon­ly used approach to cre­at­ing tech­ni­cal documents:

Authoring_process

  • Maps: When explain­ing the rela­tion­ship of one object to anoth­er, Roam rec­om­mends you use a map. When I think of maps, I tend to think of street maps. But that’s too nar­row a def­i­n­i­tion. Maps can show all sorts of things. From Roam’s book, here’s one exam­ple that explains the rela­tion­ship among objects:

Example of a map

Here’s anoth­er screen cap­ture from Roam’s book that shows an orga­ni­za­tion­al chart, which is just anoth­er type of map:

Organizational chart

  •  Flow­charts:  Flow­charts are tools that explain “how” a process works. If you’re seri­ous about flow­charts, you could use Visio. For end-user doc­u­men­ta­tion, I find Visio dia­grams too tech­ni­cal look­ing and uninvit­ing. I cre­at­ed this sim­ple flow­chart in Pow­er­Point that explains one way to review tech­ni­cal documents:

Example of flowchart

In this blog entry, I’ve just scratched the sur­face of Roam’s book. The Back of the Nap­kin is well worth a read for tech­ni­cal writ­ers who want to diver­si­fy their skill set and use visu­al think­ing to work through com­plex tech­ni­cal concepts.

Ruthlessly edit when writing for mobile

by 1 Comment

Imag­ine you have a den­tal appoint­ment and you arrive ear­ly. To kill the time, you might skim a copy of Newsweek that’s sit­ting in the wait­ing room. Or, if you are like mil­lions of peo­ple with a smart­phone, you might start perus­ing your e‑mail, surf­ing the Inter­net, or see­ing what’s new on Facebook.

Usabil­i­ty guru Jakob Nielsen com­plet­ed research that shows con­sumers are using mobile phones as time killers, per­fect for when you have five min­utes to spare. The same study also showed that peo­ple are impa­tient with any­thing that’s per­ceived as “ver­bosi­ty.”

In a typ­i­cal news­pa­per arti­cle, it’s not uncom­mon for a reporter to inter­view two to four sources when writ­ing about a nat­ur­al dis­as­ter, such as a hur­ri­cane. When con­sumers are read­ing the hur­ri­cane sto­ry on a mobile phone, they per­ceive those extra view­points as extraneous.

What does all this mean for tech­ni­cal writ­ers? If you’re writ­ing any con­tent that will be appear on a mobile phone, con­sumers want writ­ers to get to the point quickly.

It seems that peo­ple want less and less con­tent. Years ago, Nielsen rec­om­mend­ed that if you write 500 words for a print­ed doc­u­ment, prune that same mes­sage to 250 words when it’s read online. This lat­est study seems to sug­gest that we should be even more ruth­less when it comes to sum­ma­riz­ing our main messages.

It’s not sur­pris­ing that peo­ple want key mes­sages, not lengthy, nuanced expo­si­tion. Many North Amer­i­cans are feel­ing inun­dat­ed with infor­ma­tion, suf­fer­ing from “infobe­si­ty” (see my ear­li­er arti­cle about the top­ic). Many North Amer­i­cans also strug­gle with literacy—Canada has an illit­er­ate and semi­lit­er­ate pop­u­la­tion esti­mat­ed at 42 per­cent of the whole, a pro­por­tion that mir­rors that of the U.S. We’re also dis­tract­ed. It’s not uncom­mon to be “spend­ing time” with some­one when they’re furtive­ly star­ing down at their iPhone or Blackberry.

Like it or loathe it, more and more peo­ple are using smart­phones to get their infor­ma­tion. If you’re writ­ing online assis­tance for mobile users, you need to sum­ma­rize your mes­sages down to bite-sized chunks. Joe Welinske, the pres­i­dent of Writ­er­sUA, recent­ly wrote a series of webi­na­rs about mobile user assis­tance. In his book Devel­op­ing User Assis­tance For Mobile Apps, Welinske writes, “The sin­gle most impor­tant thing I have learned in my work with mobile apps is that bring­ing over Help designs from desk­top appli­ca­tions is a real­ly bad idea.”

So when you’re author­ing con­tent for a mobile envi­ron­ment, be ruth­less with your edit­ing. Imag­ine you are writ­ing for Twitter.

Here’s the full arti­cle about Nielsen’s research.

COMMUNICATING TO AN ILLITERATE AUDIENCE

by 3 Comments

With such high lev­els of func­tion­al illit­er­a­cy in North America—some esti­mates peg the num­ber at about 42 per­cent of the total population—what impli­ca­tions do num­bers like this have on pro­fes­sion­al communicators?

In his book Empire of Illu­sion, author Chris Hedges shares some star­tling sta­tis­tics about illit­er­a­cy in Cana­da and the U.S:

  • About 27 mil­lion Amer­i­cans are unable to read well enough to com­plete a job appli­ca­tion, and 30 mil­lion can’t read a sim­ple sen­tence. There are some 50 mil­lion peo­ple who read at a fourth- or fifth-grade lev­el. Near­ly a third of the nation’s pop­u­la­tion is illit­er­ate or bare­ly literate.
  • A third of high-school grad­u­ates nev­er read anoth­er book in their lives, and nei­ther do 42 per­cent of uni­ver­si­ty grads.
  • In 2007, 80 per­cent of the fam­i­lies in the U.S. didn’t buy or read a book.
  • Cana­da has an illit­er­ate and semi­lit­er­ate pop­u­la­tion esti­mat­ed at 42 per­cent of the whole, a pro­por­tion that mir­rors that of the U.S.

Giv­en these sta­tis­tics, does it always make sense to churn out book-cen­tric user guides and help systems?

As always, it depends on your audi­ence. But I believe that writ­ers will need to embrace oth­er tech­nolo­gies to con­vey mes­sages. Some ideas:

  • Using sites like Twit­ter to com­mu­ni­cate key mes­sages in 140 char­ac­ters or less.
  • Cre­at­ing how-to demon­stra­tions and videos with voiceovers may become the norm.
  • Deliv­er­ing Pod­casts for explain­ing some prod­ucts and concepts.
  • Tak­ing advan­tage of social media sites to fos­ter dia­log with customers.
  • Writ­ing con­tent for a three-inch screen, as con­sumers con­tin­ue to snap-up smart phones, such as Black­ber­rys and iPhones.

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