Your Audience

Based on the first chapters of Thomas Pearsall, The Elements of Technical Writing.

Why Are You Writing?

A (likely) lesson from earlier CMPT courses: you need to understand what problem you're trying to solve before you start programming.

Similarly, before you start writing, you need to know why you're writing. What are you trying to accomplish? Who will be reading it?

Your Purpose

Why are you writing this thing? If you don't know then… what are you doing?

Ask yourself: What is the goal? What do you hope to accomplish?

Your Purpose

For example, these are different goals:

  • to inform our team that Pandas library does many useful data analyses
  • to convince the team to use Pandas for data analysis in our project

Your Purpose

For technical writing, your goal is likely one of these: to inform or to convince.

Your Purpose

Different goals lead to different results:

The recent versions of Pandas are capable of X, Y, and Z.
In our project, we need to do X, Y, and Z. Pandas will do all of those, so it is a good choice for our project.

Your Audience

Maybe one of the most important things in the way you write is something many people don't think about: who is reading it?

You had better be writing for the people actually reading it. Otherwise, why bother?

Your Audience

A few things to highlight about the audience you can think about:

  • concerns and characteristics,
  • education and experience,
  • attitude toward the info.

Concerns & Characteristics

What does your audience care about? Why are they going to read what you have written?

Some examples (full of generalizations)…

Concerns & Characteristics

Technical/expert readers:

  • Expect practical and in-depth discussion.
  • What to know how things work.
  • Looking for how-to information or answers to questions.
  • Know the terminology and background of the field.
  • Expect conclusions to cautiously expressed.
  • Expect conclusions to be well supported.

Concerns & Characteristics

Executives:

  • Read to make decisions.
  • May not be domain experts: need more general explanations. May know general ideas but not every detail.
  • Likely less concerned with technology than with people, products, results, ….
  • ⋮

Concerns & Characteristics

Executives:

  • Expect conculsions/recommendations to be expressed clearly.
  • Need technical terms explained (or avoided).
  • Probably have a lot to read: may skim and scan.
  • Have their own goals or projects that affect their choices.

Concerns & Characteristics

General audience/laypersons:

  • Probably reading to learn, or for their own interest.
  • Won't know technical terms, or maybe the basics of the field.
  • May need simplified explanations.
  • Not a uniform group.

Concerns & Characteristics

No matter who your audience is, ask yourself what motivates them, and what do they care about?

If I give you a writing exercise and don't tell you the audience, it's incomplete.

In-Class Exercise

Write two paragraphs:

Explain what YouTube is to someone who has only used the Internet for shopping and reading news sites.

Explain it to an old computer scientist who knows all about algorithms, but only uses their computer for LaTeX.

Education & Experience

Technical writing always involves… technical things?

Your audience may or may not know exactly what you know. That needs to be take into account in your explanations.

Education & Experience

Some words we might use that others (even in a tech company) might not know (with the same meaning):

  • tree
  • sort
  • object
  • server
  • version control

Education & Experience

You will often write descriptions, explanations, recommendations, requests that will be read by non-technical people.

  • HR screening
  • project managers
  • senior staff
  • marketing staff
  • clients
  • end-users
  • ⋮

Education & Experience

It's probably wise to write something they will understand.

Doing so requires you to understand them (at least a little) and have some empathy (at least a little).

Attitude Toward Info

How receptive is your audience going to be to your content?

Will they be interested or bored? Sympathetic or hostile?

Attitude Toward Info

Example: asking your boss (office manager, whoever) for a new computer.

Their attitude is going to depend on many things: how old your existing computer is, budget status, age of others' computers, what work you do, how much they like you, ….

Attitude Toward Info

Example: writing documentation for users.

Are they interested in the product or using it because they have been forced? Is using it a big part of their job or small?

How much information do they actually need? Nobody wants to read 10 pages to get 1 page of information they want.

Attitude Toward Info

You will need to tailor your message to their state of mind.

Give more/less detail, reasons, motivation, etc. Some people want lots of details and some don't (or simply trust you).

Again: understanding your audience and having some empathy is necessary.

Audience Motivation

What do your readers actually want?

If you're asking for something (action, favour, change in opinion), what is going to actually get them to do it?

If you can figure that out, you win.

Audience Motivation

They might want…

  • to increase X by 1%/10%/100%.
  • to say “I worked on an innovative project to increase X”, regardless of results.
  • a project that addresses a priority area.
  • to appear to be doing something extra.
  • something interesting to work on.
  • to support their staff's initiatives and increase retention.
  • a raise.

Audience Motivation

If you know what your readers actually want, make sure you address it.

Maybe don't be too obvious about it, though.

If we don't do this, I'll get sad and quit.
I am really looking forward to working on this.

Audience Questions

Another perspective: things to ask (yourself, others) about your audience. [Adapted from Dawn Henwood, A Writing Guide for IT Professionals, Figure 1.3.]

  • Age, gender, job title.
  • First language.
  • Cultural differences.
  • Preferred writing style.
  • Education.

Audience Questions

  • Position in organization relative to me: set tone appropriately.
  • Relationship with you: know them well, or first communication?
  • Time with organization: how much background needed?
  • Previous work history.

Audience Questions

  • Level of technical knowledge.
  • Familiarity with topic.
  • Purpose in reading my document: make a decision, justify a decision, need to pass info along.
  • Time available to read my document.

Audience Questions

  • Interest in my document.
  • Pre-formed opinions.
  • Favourite jargon.
  • Hated jargon/terminology.

In-Class Exercise

For the CMPT 470 project, I ask for a “project proposal” for the big group project (≈50% of course mark). I ask:

The proposal should be approximately one page in length. It should describe your plans for the project, what will be implemented, and the technologies that will be used in the implementation (but you are certainly free to change technologies later).

The audience is me: what can you guess about the purpose, my concerns, characteristics, attitude, etc? Why make you write this?