Robert Desprez Communications

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

How to use illustrations to make your
technical docs clearer

September 27, 2013 by RDesprez 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.

Filed Under: Career Development, Robert Desprez | Vancouver technical writer | Blog Tagged With: career development, illustrations, online writing, technical writing, using graphics

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,208 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 Jul 2081426469667180993

Are we living in a post-literate society?

Image for twitter card

Opinion: A viral essay declares the end of reading is here. But there’s no end to its pleasures

To all Canadians who still buy books: Tell each other about the ones you love

www.theglobeandmail.com

Reply on Twitter 2081426469667180993 Retweet on Twitter 2081426469667180993 0 Like on Twitter 2081426469667180993 0 Twitter 2081426469667180993
robert_desprez avatar; Robert Desprez @robert_desprez ·
26 Jul 2081426169262674164

Image for twitter card

Being effective at work boils down to knowledge, methods, people and technology

Think of your effectiveness architecture as a two-storey house, says Melissa Swift. On the ground floor are knowledg...

www.theglobeandmail.com

Reply on Twitter 2081426169262674164 Retweet on Twitter 2081426169262674164 0 Like on Twitter 2081426169262674164 0 Twitter 2081426169262674164
Retweet on Twitter Robert Desprez Retweeted
robert_desprez avatar; Robert Desprez @robert_desprez ·
21 Jul 2079411504575877320

Being effective at work boils down to knowledge, methods, people and technology

Reply on Twitter 2079411504575877320 Retweet on Twitter 2079411504575877320 1 Like on Twitter 2079411504575877320 0 Twitter 2079411504575877320
robert_desprez avatar; Robert Desprez @robert_desprez ·
21 Jul 2079411504575877320

Being effective at work boils down to knowledge, methods, people and technology

Image for twitter card

Being effective at work boils down to knowledge, methods, people and technology

Think of your effectiveness architecture as a two-storey house, says Melissa Swift. On the ground floor are knowledg...

www.theglobeandmail.com

Reply on Twitter 2079411504575877320 Retweet on Twitter 2079411504575877320 1 Like on Twitter 2079411504575877320 0 Twitter 2079411504575877320
Load More

Recent Blog Posts

  • Using ChatGPT to read smarter
  • ChatGPT: The AI-powered proofreader
  • Four ways Confluence could be better
  • First impressions of MadCap’s purchase of IXIASOFT

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 © 2026  · Robert Desprez Communications Inc.