Robert Desprez Communications

List of Online Webinars and North American Conferences for Technical Writers

by Leave a Comment

There’s no short­age of train­ing web sites, webi­na­rs, and con­fer­ences to keep your skills sharp.

Adobe’s blog:
https://blogs.adobe.com/techcomm/

MadCap’s free webinars:
https://www.madcapsoftware.com/resources/recorded-webinars.aspx

Scrip­to­ri­um Pub­lish­ing offers time­ly and insight­ful thoughts on tech­ni­cal writ­ing trends:
https://www.scriptorium.com/blog/

The Soci­ety for Tech­ni­cal Com­mu­ni­ca­tion (STC) also offers webi­na­rs and cours­es for a fee:
https://www.stc.org/education/

Here’s a list of upcom­ing con­fer­ences this year in North America.

Lava­con, Octo­ber 21–24, 2018, New Orleans, LA
http://lavacon.org

Mad­World Con­fer­ence, June 3–6, 2018, San Diego, CA
http://www.madcapsoftware.com/events/madworld/

STC annu­al con­fer­ence, May 20–23, 2018, Orlan­do, FL
http://summit.stc.org/

Write the Docs + Open Help Cincin­nati, August 18–22, Cincin­nati, OH
http://www.writethedocs.org/conf/cincinnati/2018/

Writ­er­sUA User Assis­tance Boot Camp, Oct 4–5, 2018, Raleigh, NC
http://east.writersua.com/

How do you keep your skills up to date? Any oth­er North Amer­i­can con­fer­ences that I should add?

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.

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?

List of upcoming
technical communications conferences

by 6 Comments

Here’s a list of upcom­ing con­fer­ences this year in North America.

Intel­li­gent Con­tent Con­fer­ence, March 23–25, San Francisco
http://www.intelligentcontentconference.com/

Mad­World 2015 World­wide Learn­ing Con­fer­ence, April 12–14, San Diego
http://www.madcapsoftware.com/events/madworld/

Writ­er­sUA User Assis­tance Boot Camp, April 15–17, Seattle
http://west.writersua.com/

Con­tent Man­age­ment Strategies/DITA North Amer­i­ca, April 20–22, Chicago
http://www.cm-strategies.com/2015/index.htm

IA Sum­mit, April 22–26, Minneapolis
http://www.iasummit.org/

Write the Docs 2015, May 17–19, Portland
http://www.writethedocs.org/conf/na/2015/

STC annu­al con­fer­ence, June 21–24, Columbus
http://summit.stc.org/

Lava­con, Octo­ber 18–21, New Orleans
http://lavacon.org

How do you keep your skills up to date? Any oth­er North Amer­i­can con­fer­ences that I should add?

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