Robert Desprez Communications

  • My Services
  • My Blog
  • About Me
  • Contact Me

Five Reasons I Like Confluence

February 7, 2018 by RDesprez 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.

Filed Under: Help Authoring Tools, Online Collaboration, Robert Desprez | Vancouver technical writer | Blog, Technology Tagged With: Confluence, five reasons to like Confluence, technical writing, wikis

SharePoint 2010 for technical writers

July 6, 2012 by RDesprez 7 Comments

When I first start­ed using Share­Point, I have to admit that I was not impressed.

The user inter­face felt unin­spired. Some soft­ware user inter­faces draw you in. For me, Share­Point was­n’t one of them. I remem­ber won­der­ing, “Why would I want to use this?”

I’ve changed my tune. After learn­ing more about Share­Point’s ben­e­fits and using it at sev­er­al client sites, I rec­og­nize that it offers a num­ber of ben­e­fits to tech­ni­cal writers:

* Share­Point pro­vides a basic Con­tent Man­age­ment Sys­tem (CMS). Peo­ple use a CMS to pub­lish, edit, and man­age con­tent, such as doc­u­ments. A full-blown CMS is expen­sive where­as Share­Point is fre­quent­ly already installed in larg­er orga­ni­za­tions. Tech­ni­cal writ­ers can use it to gain con­trol over their doc­u­ments at the file level.

* Share­Point Foun­da­tion 2010 is free. Share­Point 2010 is avail­able in two flavours: Share­Point Serv­er 2010 and Share­Point Foun­da­tion. Share­Point Serv­er offers more fea­tures than Share­Point Foun­da­tion but the lat­ter is free.

* You can use meta­da­ta to tag your files. If you are work­ing on a lot of con­tent, adding meta­da­ta to your files may be a worth­while invest­ment because it helps group your con­tent into cat­e­gories. Meta­da­ta is a col­lec­tion of cen­tral­ly man­aged terms that you can define and then use as attrib­ut­es for a file. Then, after you have tagged your con­tent, oth­er writ­ers can search for doc­u­ments using the same categories—content is eas­i­er to find and update.

* Source con­trol. Share­Point requires you to check out files before you edit them and offers ver­sion con­trol of the file. Ver­sion con­trol essen­tial­ly keeps a his­to­ry of the file. If for some rea­son you want to res­ur­rect an ear­li­er ver­sion of a doc­u­ment, Share­Point makes it easy.

* Col­lab­o­ra­tion. Share­Point enables teams to col­lab­o­rate on files. If you are work­ing with anoth­er per­son on a file, each writer can work on the con­tent con­cur­rent­ly and the lat­est ver­sion is then uploaded to the Share­Point site.

* Doc­u­ment con­trol. Share­Point makes it pos­si­ble to restrict users at the site lev­el. Best prac­tices sug­gest assign­ing employ­ees or con­trac­tors to user groups.

* Work­flows. In Share­Point, you can auto­mate the review process. As a writer, you can cre­ate a list of review­ers and add dead­lines. Share­Point then sends e‑mails to SMEs and sends you an e‑mail when they have reviewed the document.

* Trans­la­tion work­flows. If you need to trans­late your con­tent, Share­Point can assist with the process by remind­ing exter­nal stake­hold­ers to per­form tasks by cer­tain dates, and e‑mails you when all of the work is complete.

* Easy to use. Share­Point has a sim­i­lar look and feel to oth­er Microsoft Office prod­ucts. It sports the famil­iar Microsoft rib­bon and the tasks are pret­ty straight­for­ward (for tech­ni­cal writ­ers, at least).

* Lots of sup­port con­tent. There are many books, web sites, and blogs about Share­Point. For exam­ple, check out these online train­ing courses.

The bot­tom line: Share­Point is a worth­while tool if col­lab­o­ra­tion is impor­tant and you need con­trol over your source files. Sounds like a good fit for most tech­ni­cal writers.

Filed Under: Career Development, Online Collaboration, Robert Desprez | Vancouver technical writer | Blog, Technology, Web 2.0 Tagged With: benefits of SharePoint, technical writers

Three reasons you should allow comments in your documentation

February 21, 2012 by RDesprez 9 Comments

Mil­lions of peo­ple around the world are post­ing blog entries and com­ment­ing on those posts. But tech­ni­cal writ­ers have remained on the side­lines by not let­ting our users com­ment on our content.

Here are three rea­sons you should enable commenting:

Rea­son #1: Peo­ple are used to writ­ing com­ments on blogs and web pages. Mil­lions of peo­ple post blog posts. And thou­sands of us add our com­ments to those posts. For the most part, tech­ni­cal writ­ers haven’t embraced this fea­ture. I’d haz­ard a guess that most online help or even sup­port web pages do not sup­port user comments.

I recent­ly read Clay Shirky’s book Cog­ni­tive Sur­plus. Shirky argues that in decades past North Amer­i­cans spent a lot of time watch­ing TV. But with the Inter­net, peo­ple are spend­ing much less time pas­sive­ly sit­ting on the couch. We’re par­tic­i­pat­ing online writ­ing blogs, cre­at­ing YouTube videos, and writ­ing and edit­ing con­tent on web sites like Wikipedia. Just a small change in how peo­ple spend their time can have aston­ish­ing changes in our world. He writes:
“Imag­ine that every­thing stays 99 per­cent the same, that peo­ple con­tin­ue to con­sume 99 per­cent of the tele­vi­sion they used to but 1 per­cent of that time gets carved out for pro­duc­ing and shar­ing. The con­nect­ed pop­u­la­tion still watch­es over a tril­lion hours of TV a year; 1 per­cent of that is more than 100 Wikipedias worth of par­tic­i­pa­tion per year.”

So the Inter­net has rev­o­lu­tion­ized how we spend our free time. As cit­i­zens and con­sumers, we are active­ly con­tribut­ing to con­tent. But tech­ni­cal writ­ers have remained on the side­lines by not let­ting our users com­ment on our content.

Rea­son #2: Col­lab­o­ra­tion helps cre­ate an online com­mu­ni­ty. Col­lab­o­ra­tion offers a num­ber of benefits:

* An online com­mu­ni­ty can help each oth­er share solu­tions, workarounds, and trou­bleshoot­ing tech­niques. Tech­ni­cal writer and author Anne Gen­tle writes in her book Con­ver­sa­tion and Com­mu­ni­ty : “…a com­mu­ni­ty of prac­tice can form now that online tools speed up the process of teach­ing spe­cif­ic tech­niques and learn­ing them from oth­ers.” Work­ers can spend about a third of their time look­ing for infor­ma­tion. An online com­mu­ni­ty is one of the ways that users can find infor­ma­tion quickly.

* An online com­mu­ni­ty builds good­will among your users. If your com­pa­ny has seri­ous­ly invest­ed a lot of time and mon­ey in an online com­mu­ni­ty with facil­i­ta­tors that respond help­ful­ly and quick­ly, the com­pa­ny slow­ly builds pos­i­tive good­will among its users. Over time, your com­pa­ny may be rec­og­nized as an inno­v­a­tive provider of support―potentially a dif­fer­en­tia­tor when com­pared to your competitors.

* An online com­mu­ni­ty can improve your con­tent. We all have blind spots. Maybe your online help doesn’t con­tain the key con­tent that users need. Per­haps they’re look­ing for specifics on a dif­fi­cult task. With an active and engaged com­mu­ni­ty, it won’t be long before some­one starts point­ing out the miss­ing pieces in your content.

Rea­son #3: Learn­ing new skills for writ­ers. Tech­ni­cal writ­ers are used to inter­view­ing SMEs, and draft­ing and edit­ing con­tent. By post­ing your doc­u­men­ta­tion and act­ing as a facil­i­ta­tor for user com­ments, you may learn about blog­ging soft­ware and HTML (depend­ing on which tool you use), and online diplo­ma­cy. Anne Gen­tle writes: “Con­sid­er becom­ing a mod­er­a­tor only after you have been a par­tic­i­pant for a while. Most online com­mu­ni­ties do not rec­og­nize any sense of enti­tle­ment that you may have because of your employ­er. Instead you must earn the community’s trust and offer real help, even if you only pro­vide links to your online help. Teach­ing the com­mu­ni­ty to fish (for infor­ma­tion) feeds them longer than just answer­ing ques­tions with­out cit­ing how you learned the infor­ma­tion yourself.”

Of course, I should point out that enabling com­ment­ing is no guar­an­tee of doc­u­men­ta­tion nir­vana. You may be sub­ject to spam­mers, your com­pa­ny needs to devote at least one per­son to mon­i­tor and respond to user com­ments, and you’ll prob­a­bly notice that a minor­i­ty of your users are the most like­ly to comment.

Here are a few exam­ples of online doc­u­men­ta­tion that encour­ages online dis­cus­sions and comments:

Microsoft’s Devel­op­er Net­work is one of the first exam­ples of com­mu­ni­ty-con­tributed content.
http://msdn.microsoft.com/en-us/library/ff851953.aspx#6

Atlass­ian allows users to post com­ments on its doc­u­men­ta­tion wiki.
http://confluence.atlassian.com/display/DOC/Confluence+Documentation+Home

On a relat­ed note, I wrote a blog entry about how to add com­ments to your doc­u­men­ta­tion using third-par­ty tools, such as Dis­qus and Wufoo.

Filed Under: Online Collaboration, Robert Desprez | Vancouver technical writer | Blog Tagged With: collaboration, Documentation, user feedback

WAYS TO USE TECHNOLOGY TO CONNECT WITH USERS

September 5, 2011 by RDesprez 1 Comment

Most tech­ni­cal writ­ers have lit­tle idea how their deliv­er­ables are used, if at all.

We strive to ensure that the con­tent is tech­ni­cal­ly cor­rect, that the deliv­er­ables adhere to the com­pa­ny style guide, and that the items ship before or on the agreed-upon deadlines.

After suc­cess­ful­ly ship­ping, mean­ing­ful user feed­back is hard­ly a del­uge, if there’s any­thing at all. More real­is­ti­cal­ly, it is a trickle—some anec­do­tal feed­back that a user liked some­thing we wrote, or an e‑mail that the sales rep­re­sen­ta­tive thought it hit the mark.

Web 2.0 makes it eas­i­er to con­nect to users. Any­one with an Inter­net con­nec­tion and a com­put­er can cre­ate a YouTube video, add some con­tent to a Wikipedia page, write a blog, and so on. For tech­ni­cal writ­ers, this means it’s easy for our users to add com­ments on our help top­ics or web pages.

Here are two rel­a­tive­ly simple—and free—ways you can use tech­nol­o­gy to con­nect with your users.

Feed­back Forms and Commenting
At http://wufoo.com/examples/, you can add many types of forms to a web page or help top­ic with­out hav­ing to code any­thing. Using an embed­ded Con­tact Form, your users do not have to leave the site and you do not have to dis­sem­i­nate an email address that could be a tar­get of spam mail.

Anoth­er site worth vis­it­ing is http://disqus.com, which enables your users to add com­ments to a web site or online help top­ic. Sim­i­lar to a blog, your users can respond to a help top­ic that you’ve writ­ten and you can mon­i­tor and respond to the feed­back by e‑mail using your com­put­er, iPhone, or Android phone. Dis­qus also enables users to click a but­ton when they like a top­ic or web page you’ve authored, with­out requir­ing them to add a comment.

If you’d pre­fer not to add HTML code to your online help or web pages, you can also use Adobe Robo­Help to enable com­ment­ing as you long as you use the company’s Adobe AIR out­put for­mat. To learn more about the details of this option, vis­it tech­ni­cal writer Sarah Maddox’s blog.

Filed Under: Online Collaboration, Robert Desprez | Vancouver technical writer | Blog Tagged With: collaboration, Documentation, technology, tools, user feedback

IS HELP 2.0 HYPED?

June 29, 2011 by RDesprez 2 Comments

There’s been a lot of dis­cus­sion about “Help 2.0” in which users will be able to eas­i­ly com­ment on the con­tent you’ve writ­ten in a help topic.

The Soci­ety for Tech­ni­cal Communication’s Inter­com mag­a­zine recent­ly pub­lished an arti­cle titled “Under­stand­ing the Help 2.0 Rev­o­lu­tion.” I have to admit that I thought the arti­cle con­tained some excit­ing ideas: for the first time tech­ni­cal writ­ers may have an online dia­log with our read­ers using tech­nolo­gies like web posts and commenting.

In the same vein, author and teacher Clay Shirky wrote a book called Cog­ni­tive Sur­plus. In it, he asserts that North Amer­i­cans are watch­ing less tele­vi­sion and are embrac­ing col­lab­o­ra­tive tech­nolo­gies like blogs and wikis. Col­lec­tive­ly, we can pool our efforts to achieve amaz­ing results. Just look at the colos­sal effort of web sites like Wikipedia.

But I think we have a long way to go. For all this talk of col­lab­o­ra­tion, usabil­i­ty guru Jakob Nielsen argues that only one per­cent of peo­ple con­tribute to a site, nine per­cent are inter­mit­tent con­trib­u­tors, and 90 per­cent just read the con­tent. So if Nielsen is right, most peo­ple are still being pas­sive. Doesn’t sound that dif­fer­ent to watch­ing television.

Here’s an excerpt from Nielsen’s web site:

“Blogs have even worse par­tic­i­pa­tion inequal­i­ty than is evi­dent in the 90–9‑1 rule that char­ac­ter­izes most online com­mu­ni­ties. With blogs, the rule is more like 95–5‑0.1. Inequal­i­ties are also found on Wikipedia, where more than 99% of users are lurk­ers. Accord­ing to Wikipedi­a’s “about” page, it has only 68,000 active con­trib­u­tors, which is 0.2% of the 32 mil­lion unique vis­i­tors it has in the U.S. alone.”

Grant­ed, Nielsen’s research is about five years old. Maybe more peo­ple are now con­tribut­ing? But I doubt it’s sig­nif­i­cant­ly more.

Here‘s the bot­tom line. If you’ve cre­at­ed a web site or help sys­tem that incor­po­rates Web 2.0 tech­nolo­gies like com­ment­ing, don’t be sur­prised if you ini­tial­ly receive a trick­le of respons­es from your read­ers. My bet is that tech­ni­cal writ­ers will need to reg­u­lar­ly pro­mote their help sys­tems or web sites to encour­age more read­ers to post their feed­back. If you want an online dia­log with cus­tomers, it‘s not just a mat­ter of “build it and they will come.”

Filed Under: Online Collaboration, Robert Desprez | Vancouver technical writer | Blog Tagged With: collaboration, Documentation, Help Authoring Tools, technology, tools, user feedback

  • 1
  • 2
  • Next Page »

About Robert Desprez

I have worked as a Vancouver technical writer for more than 20 years, working at some of British Columbia's largest high-tech firms. I have served in leadership positions for the Society for Technical Communication and have worked as a writing instructor at Vancouver's Simon Fraser University.

Robert Desprez Follow 1,147 239

Vancouver Technical Writer. Former Instructor at Simon Fraser University. Dog Lover. Coffee Drinker. Tennis and Piano Player.

robert_desprez
robert_desprez avatar; Robert Desprez @robert_desprez ·
16 May 1923413647243559161

Image for twitter card

I Regret My Tesla | The Walrus

I wanted to be good. Then the car company fell from grace

thewalrus.ca

Reply on Twitter 1923413647243559161 Retweet on Twitter 1923413647243559161 0 Like on Twitter 1923413647243559161 0 Twitter 1923413647243559161
robert_desprez avatar; Robert Desprez @robert_desprez ·
16 May 1923413050498957392

Image for twitter card

Brian Chesky Lost His Mind One Night—and Now He's Relaunching Airbnb as an Everything App

Airbnb's CEO is spending hundreds of millions to relaunch his travel company as an all-purpose service app. Fitness!...

www.wired.com

Reply on Twitter 1923413050498957392 Retweet on Twitter 1923413050498957392 0 Like on Twitter 1923413050498957392 0 Twitter 1923413050498957392
robert_desprez avatar; Robert Desprez @robert_desprez ·
16 May 1923412665478627824

Toronto Centre MP Evan Solomon appointed Canada’s first AI minister /via @globeandmail

Image for twitter card

Toronto Centre MP Evan Solomon appointed Canada’s first AI minister

Experts say Solomon could face a host of challenges in his role, including how to increase AI adoption and comme...

www.theglobeandmail.com

Reply on Twitter 1923412665478627824 Retweet on Twitter 1923412665478627824 0 Like on Twitter 1923412665478627824 0 Twitter 1923412665478627824
robert_desprez avatar; Robert Desprez @robert_desprez ·
2 May 1918126029463536113

This productivity poison is exhausting you /via @globeandmail

Image for twitter card

This productivity poison is exhausting you

Constantly shifting your attention undermines what is your super power in most knowledge jobs. How you anticipate an...

www.theglobeandmail.com

Reply on Twitter 1918126029463536113 Retweet on Twitter 1918126029463536113 0 Like on Twitter 1918126029463536113 0 Twitter 1918126029463536113
Load More

Recent Blog Posts

  • ChatGPT: The AI-Powered Proofreader
  • Four Ways Confluence Could Be Better
  • First impressions of MadCap’s purchase of IXIASOFT
  • Online Conferences for Technical Writers in 2023

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

  • Email
  • LinkedIn
  • Twitter

Copyright © 2025  · Robert Desprez Communications Inc.