Based on the first chapters of Thomas Pearsall, The Elements of Technical 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?
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?
For example, these are different goals:
For technical writing, your goal is likely one of these: to inform or to convince.
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.
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?
A few things to highlight about the audience you can think about:
What does your audience care about? Why are they going to read what you have written?
Some examples (full of generalizations)…
Technical/expert readers:
Executives:
Executives:
General audience/laypersons:
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.
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.
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.
Some words we might use that others (even in a tech company) might not know (with the same meaning):
You will often write descriptions, explanations, recommendations, requests that will be read by non-technical people.
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).
How receptive is your audience going to be to your content?
Will they be interested or bored? Sympathetic or hostile?
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, ….
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.
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.
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.
They might want…
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.
Another perspective: things to ask (yourself, others) about your audience. [Adapted from Dawn Henwood, A Writing Guide for IT Professionals, Figure 1.3.]
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?