Robert Desprez Communications

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

FrameMaker 12 documentation disappoints

March 22, 2015 by RDesprez 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?

Filed Under: Help Authoring Tools, Online Writing, Robert Desprez | Vancouver technical writer | Blog Tagged With: FrameMaker, Help Authoring Tools, online writing

Ways to keep your skills sharp

March 2, 2014 by RDesprez 3 Comments

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

As I stat­ed in an ear­li­er blog entry, I believe it’s up to you to keep your­self mar­ketable and cre­ate your own train­ing plan. I like this quote from a recruiter: “You can’t rely on a com­pa­ny for your growth and train­ing anymore…Except for a few enlight­ened com­pa­nies, if they’re train­ing you at all, they’re train­ing you for what they need, not nec­es­sar­i­ly train­ing for what you need to devel­op your tech­ni­cal skills over the long run.”

My pro­fes­sion­al devel­op­ment plan includ­ing attend­ing a con­fer­ence every two to three years, aug­ment­ed with reg­u­lar self-direct­ed learn­ing. The last few years I’ve attend­ed and pre­sent­ed at two Writ­er­sUA con­fer­ences. Between con­fer­ences, I sign up for tech­ni­cal writ­ing webi­na­rs and read busi­ness and tech­nol­o­gy books. I also sub­scribe to Wired. Last year, I signed up for a mem­ber­ship to Lynda.com.

Lynda.com

Lynda.com teach­es com­put­er skills in video for­mat to mem­bers through month­ly and annu­al sub­scrip­tion-based plans. I’ve found it help­ful for learn­ing how to cre­ate EPUBs and brush­ing up on Robo­Help, FrameMak­er, Microsoft Office pro­grams, Cas­cad­ing Style Sheets (CSS), and Search Engine Opti­miza­tion for web sites.  One glar­ing exception—Lynda.com does not offer train­ing for Mad­Cap Flare.

Recorded webinars

I reg­u­lar­ly watch record­ed webinars.

Adobe offers free record­ed videos for tech­ni­cal writers:

http://tinyurl.com/y3j72x

Mad­Cap also offers free webinars:

http://tinyurl.com/lv8vrcq

Scrip­to­ri­um Pub­lish­ing offers time­ly and insight­ful thoughts on tech­ni­cal writ­ing trends:

http://tinyurl.com/kxa67qn

The Soci­ety for Tech­ni­cal Com­mu­ni­ca­tion also offers webi­na­rs for a fee:

http://tinyurl.com/mhvkg8a

Conferences

Here’s a sum­ma­ry of upcom­ing con­fer­ences this year.

Mad­World 2014 World­wide Learn­ing Con­fer­ence, April 13–15, San Diego
http://www.madcapsoftware.com/events/madworld/

Con­tent Man­age­ment Strategies/DITA North Amer­i­ca 2014, April 28–30, Seattle
http://www.cm-strategies.com/2014/index.htm

STC annu­al con­fer­ence, May 18–21, Phoenix
http://summit.stc.org/program-info/program-overview/

Lava­con, Octo­ber 13–15, 2014, Portland
http://lavacon.org/2014/about-portland/

How do you keep your skills current?

Filed Under: Career Development, Help Authoring Tools, Online Writing, Robert Desprez | Vancouver technical writer | Blog, Search Engine Optimization, Technology Tagged With: career development, conferences, learning web sites, technical writers, webinars

OFFERING TOO MUCH CHOICE MAY OVERWHELM READERS

June 20, 2010 by RDesprez Leave a Comment

When you write pro­ce­dures, do you offer your read­ers more than one way to com­plete a task? Some writ­ers go to pains to explain one pro­ce­dure and then offer alter­na­tives. For example:

1. Click the Select button.
OR
From the Options menu, click Select.
OR
From the Actions sec­tion, click Select.

This approach is pret­ty com­mon and is con­sis­tent with the North Amer­i­can belief that choice is empow­er­ing and pro­vides greater satisfaction.

Author Bar­ry Schwartz dis­agrees. In his book the Para­dox of Choice, he con­tends that too much choice can make deci­sion-mak­ing a chal­lenge. In the long-term, he argues that this leads to deci­sion-mak­ing paral­y­sis, anx­i­ety, and stress. He even sug­gests that too many choic­es in one’s life can lead to clin­i­cal depression.

In just one exam­ple in the book, Schwartz doc­u­ments the bewil­der­ing options that he faced when vis­it­ing his local supermarket:

  • Eighty vari­eties of pain relievers
  • One hun­dred and six­teen types of skin cream
  • Three hun­dred and six­ty types of con­di­tion­ers, sham­poos, gels, and mousse.
  • Nine­ty types of cold reme­dies and decongestants
  • Nine­ty-five snack options
  • Six­ty-five box drinks
  • And so on…

Schwartz points out that sev­er­al stud­ies have con­clud­ed that peo­ple are less sat­is­fied when faced with a large array of choic­es. Few­er options may actu­al­ly make one’s life easier.

In keep­ing with this research, as tech­ni­cal writ­ers, per­haps we should also stream­line the num­ber of choic­es we offer our users. It makes our lives eas­i­er and our read­ers could very well pre­fer the sim­pler, more stream­lined approach.

Filed Under: Online Writing, Robert Desprez | Vancouver technical writer | Blog, Technology Tagged With: deluge of information, technical writing, too much choice

WHY WRITING LESS CAN OFFER MORE

April 8, 2010 by RDesprez 3 Comments

I love the idea of sim­plic­i­ty in both my per­son­al and pro­fes­sion­al lives.

At this stage in my life, most of the rou­tine mate­r­i­al items I buy offer me lit­tle plea­sure. In our soci­ety, con­sumers are promised by cor­po­ra­tions that mate­ri­al­ism will bring us plea­sure. But too much stuff can become a bur­den (at least, that’s what I’ve been told) because some­one needs to sort, insure, and main­tain all these assets. Too many items also cre­ates visu­al clut­ter in a home.

I think one can apply the same ideas of sim­plic­i­ty to tech­ni­cal doc­u­men­ta­tion. Occa­sion­al­ly, I’ve worked with writ­ers who tend to write a lot about a sub­ject, some­times unnec­es­sar­i­ly. They write para­graphs about a sub­ject when one will do. In my opin­ion, these writ­ers just love to write and they share every­thing they know about a sub­ject. This to me is just more clutter.

Writ­ing less is even more impor­tant for an online envi­ron­ment. Usabil­i­ty guru Jakob Nielsen argues that online writ­ers should strive to write half of the con­tent they would for a print­ed doc­u­ment. When I am faced with a lot of scrolling on a web site or in an online help sys­tem, I find the con­tent can usu­al­ly be edit­ed or reor­ga­nized so the mate­r­i­al is eas­i­er to digest. Here are a few ben­e­fits of writ­ing less:

  • Your users get to the point faster as they won’t have to endure end­less scrolling online.
  • Less time required to write and edit reams of content.
  • Trans­la­tion costs will be lower.

It’s not eas­i­er to write less con­tent. Writ­ing less is often hard­er because I usu­al­ly have too much con­tent that needs to be stream­lined. But it’s a worth­while goal. Less is more.

Filed Under: Online Writing, Robert Desprez | Vancouver technical writer | Blog, Technology Tagged With: deluge of information, technical writing, too much choice

WEB ANALYTICS FOR TECHNICAL COMMUNICATORS

February 26, 2010 by RDesprez Leave a Comment

Tech­ni­cal com­mu­ni­ca­tion depart­ments his­tor­i­cal­ly have had lit­tle idea how their deliv­er­ables were used, if at all.

More often than not, depart­ments assid­u­ous­ly worked to make sure that the con­tent was tech­ni­cal­ly cor­rect, that the deliv­er­ables adhered to the com­pa­ny style guide, and that the items were shipped before or on the agreed-upon deadlines.

After suc­cess­ful­ly ship­ping, mean­ing­ful feed­back was hard­ly a del­uge. More real­is­ti­cal­ly, it was a trickle—some anec­do­tal feed­back that a user liked it, or an e‑mail that the sales rep­re­sen­ta­tive thought it hit the mark. Talk about walk­ing through the fog.

Web ana­lyt­ics soft­ware changes that dynam­ic. By adding a few lines of code to an intranet site, a help sys­tem that is host­ed on a web serv­er, or a sup­port web site, you can quickly:

  • Dis­cern about how many peo­ple are view­ing a cer­tain web page (such as a trou­bleshoot­ing item) for a peri­od of time.
  • Dis­cov­er how long users spend on a web page.
  • Learn where the cus­tomer is phys­i­cal­ly locat­ed (that is, the coun­try they live in).
  • Under­stand the pop­u­lar­i­ty of dif­fer­ent deliv­er­ables, such as PDF files.

All of this data pro­vides tech­ni­cal com­mu­ni­ca­tors with insights into how con­tent is used, and ideas of where to direct your efforts.

Here’s one real-life exam­ple. My soft­ware team learned that users didn’t under­stand one facet of the soft­ware. Respond­ing to that need, we cre­at­ed the doc­u­ment, local­ized it into sev­en lan­guages, and mon­i­tored its pop­u­lar­i­ty when it was post­ed to our sup­port web site. Our users appeared to like it—using web ana­lyt­ics we could con­firm that it was one of the most accessed doc­u­ments for months.

We may not get to phys­i­cal­ly vis­it users as much as we’d like. But web ana­lyt­ics at least gives us some sem­blance of how doc­u­ments are used.

Filed Under: Career Development, Online Writing, Robert Desprez | Vancouver technical writer | Blog, Technology, Web 2.0 Tagged With: career development, technical writing, web analytics

  • « Previous Page
  • 1
  • 2
  • 3
  • 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,149 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 ·
26 May 1927021047175430324

How to throw a little luck into your career /via @globeandmail

Image for twitter card

How to throw a little luck into your career

What if you could create some of your own luck?

www.theglobeandmail.com

Reply on Twitter 1927021047175430324 Retweet on Twitter 1927021047175430324 0 Like on Twitter 1927021047175430324 0 Twitter 1927021047175430324
robert_desprez avatar; Robert Desprez @robert_desprez ·
20 May 1924848939888738806

Is AI helping workers and improving productivity or just creating more work? /via @globeandmail

Image for twitter card

Is AI helping workers and improving productivity or just creating more work?

To reap the full benefits of AI, companies must be more creative than using it to automate existing tasks, one expert says

www.theglobeandmail.com

Reply on Twitter 1924848939888738806 Retweet on Twitter 1924848939888738806 0 Like on Twitter 1924848939888738806 0 Twitter 1924848939888738806
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
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.