Lecture Notes: What Is Technical Writing?

So What Is Technical Writing?

You’ve signed up for a class in technical writing, and my guess is that at least some of you are unsure what that even means.

Start with the official description of this course, as the State of Texas defines it:

Intensive study of and practice in professional settings. Focus on the types of documents necessary to make decisions and take action on the job, such as proposals, reports, instructions, policies and procedures, e-mail messages, letters, and descriptions of products and services. Practice individual and collaborative processes involved in the creation of ethical and efficient documents.

Notice the emphasis: documents that help people make decisions and take action on the job. Not documents that display what you know. Documents that get something done.

Some people use “technical writing” to mean writing about technical subjects — software documentation, scientific reports, engineering specs. In this course we’ll use it more broadly: technical writing is any writing you do as part of your job, technical field or not.

Technical Writing vs. Academic Writing

You’ve been writing in school for years, and virtually all of you took English 1301 as a prerequisite. But workplace writing differs from school writing in two ways that matter more than the rest.

Technical writing is a real career — you can be hired as a technical writer — but most technical writing is produced by people whose job titles have nothing to do with writing. If your career requires a college degree, you will be asked to write on the job, and the writing you’ll be asked to do is the kind this class covers.

Why it matters: In a 2016 employer survey, writing skills ranked third among desirable traits in a potential employee, behind only leadership and the ability to work on a team — something we’ll also practice this semester. A separate survey found more than half of employers used writing ability as a criterion for promotion.

1. School writing is about you. Technical writing isn’t.

When you write an essay for a class, the real subject is your competence, and you’re rewarded for it with a grade. Workplace writing is about the task — you’re not proving you can write a report, you’re trying to get something done. And that writing usually doesn’t belong to you. Look at the manual that came with a new pair of earbuds: no author listed. As far as the world is concerned, everything written by someone at Apple was written by Apple.

2. Nobody wants to read what you write at work.

This may be the most important point we’ll cover all semester. People read your workplace writing because they have to, not because they want to. That sounds harsh, but remember — technical writing isn’t about you. It’s the nature of the workplace. You probably tried to make those earbuds work without reading the instructions, and threw the instructions away the moment the earbuds worked. Somebody wrote them knowing almost nobody would want to read them. The same holds inside an organization: I read my colleagues’ emails every day because they contain information I need, almost never because I want to.

Step-by-Step: The Technical Writing Process

Good technical documents are not produced in a single sitting.

They’re built in stages, and each stage depends on the one before it. We’ll use a six-step process in this course:

1	ANALYZE	Purpose, genre, and audience
2	RESEARCH	Sources, expert information and data, direct experience
3	STRUCTURE	Key ideas, style guide, outline, template, layout
4	WRITE	A detailed working draft
5	INTEGRATE DATA & GRAPHICS	Tables, charts, screenshots, diagrams
6	REVIEW & REVISE	Feedback, revision, and a final draft

You’ll practice each step during the first half of the semester, then run the whole process yourself on your Final Project.

Meet Marisol

To see how the six steps connect, we’ll follow one student through all of them.

Marisol works as a receptionist at a dental practice, and that’s the field she’s chosen for her project. She hasn’t picked a topic she finds interesting in the abstract. She’s picked a problem she runs into every day.

THE PROBLEM

When a patient walks into her office, a series of things has to happen: greet them, confirm who they are, check their paperwork, verify their insurance, get them seated, handle payment afterward, and book their next visit before they walk out.

Nobody has ever written that sequence down. It lives in habit, in a few sticky notes on the monitor, and in prompts the scheduling software throws up at various points. Some steps get done twice by two different people. Some get skipped entirely on a busy morning. New employees learn it by watching, which means they also inherit whatever bad habits they happen to observe.

Marisol’s goal isn’t to document how the office works or to propose reorganizing it. Her goal is narrower and more useful: produce a one-page checklist that gets every required step of a patient visit done, in order, exactly once — from the moment the patient walks in to the moment they leave with their next appointment booked.

That’s a small document. It is also a real one, of a kind that exists in every workplace you will ever enter, and building it well turns out to require every step of the process. Watch how each step narrows the checklist rather than expanding it.

1	ANALYZE

DEFINITION: Identify and consider purpose, genre, and audience.

1. How To Do It

State your purpose as an action. What must the reader do after reading this? Everything else in this step follows from that answer.
Identify the genre that purpose calls for, and look at how that kind of document is normally built.
Name the reader who has to carry out that action, as specifically as you can. Not “the public” — the actual person who will be holding this document.
List what that reader already knows and what they don’t.
Write down your constraints: length, format, and the conditions the reader will be reading under.

2. Marisol’s Project

Purpose: get the front desk to complete every required step of a patient visit, in order, none repeated and none skipped. She writes it as an action so she can test any draft against it.
Genre: the reader needs it during the visit, which rules out a memo (filed and forgotten) and a manual (too long to consult at the counter). A checklist is the only form you can mark as you go.
Reader: Devin, six weeks in. If it works for the newest person, it works for the other two.
Knows / doesn’t: he knows the software and where forms live. He doesn’t know which steps are legally required, or that booking the next appointment is his job.
Constraints: used standing up, forty seconds, patient watching. One page, one side, readable at arm’s length.

3. Key Insights

If you can’t state your purpose with a verb, you don’t have one yet. Ginny Redish, who spent a career on plain language and document design, frames every document as a conversation a reader started for a reason. “Understand our intake process” describes territory. “Complete every required step, once” describes an outcome you can test a draft against.
Genre is a decision, and most people skip it. The default move is to reach for whatever format you used last time, which is how offices end up with eleven-page manuals nobody opens. John Carroll and Mary Beth Rosson named the reason at IBM in the 1980s: the paradox of the active user. People don’t read the manual first. They start doing the task and consult only what’s in front of them. A document meant to be used during the work has to be built differently than one meant to be read before it.
Write for the least expert person who will actually use it. Once you know a process, you cannot un-know it, and every gap in your document looks obvious to you and invisible to nobody else. Naming one real, specific reader — not a job title — is the cheapest protection against that blindness.
Easily missed: your constraints are content decisions in disguise. “One page, forty seconds, read standing up” eliminates more possibilities than any outline will. Write the constraints down in Step 1 and you will spend Step 3 designing instead of negotiating with yourself.

2	RESEARCH

DEFINITION: Identify and gather key information from sources, expert information and data, and direct experience.

1. How To Do It

Find the governing standard, guideline, regulation, or policy you’re obligated to follow.
Gather published expert information and data — professional association guidance, peer-reviewed studies, agency statistics, manufacturer specifications, industry reports.
Collect existing documents that already do this job, and compare them against each other.
Look for evidence of what goes wrong: error and incident records, complaint data, FAQs, published studies of where readers fail.
Draw on your own direct experience and observation, and record where every piece of information came from as you gather it.

2. Marisol’s Project

Governing rules: privacy acknowledgment, insurance verification, and state recordkeeping requirements. Six steps come straight from these and can’t be trimmed.
Published expertise: a dental association’s front-office guidance gives her a standard sequence. Checklist research tells her they fail by being too long — so she has a length ceiling before she drafts.
Existing documents: two published sample checklists, four sticky notes, and a 2019 handout from a former manager. Comparing them separates standard steps from local invention.
What goes wrong: six months of records show rejected claims traced to one un-updated field, three missing privacy forms, and 38% of patients leaving without a next appointment.
Direct experience: she works the desk, so she knows the sequence breaks during a mid-checkout walk-in. She logs every source, so each step has a defensible origin.

3. Key Insights

Expertise usually reaches you as a product, not a conversation. You will rarely get an hour with a specialist. But specialists publish constantly — association guidance, standards, technical bulletins, peer-reviewed studies — and that published work is the expert input most working professionals actually use.
Your organization’s own failure data beats anyone’s best practices. When Atul Gawande’s team rolled out the WHO surgical checklist, they handed each pilot hospital its own failure numbers first, so staff could see exactly which problem the checklist was built to solve. Local evidence persuades in a way that outside authority doesn’t — and it tells you which steps deserve the emphasis.
A regulation is the floor, not the document. It tells you what you cannot contradict. It never tells you what your reader needs, and a document that only satisfies the regulation usually fails the reader.
Easily missed: log your sources while you gather them. This is partly ethics — you may have to prove where a claim came from. It’s also survival. The first question a supervisor asks about any new document is “why is this step in here?”, and “it seemed important” is not an answer that survives contact with a manager.

3	STRUCTURE

DEFINITION: Develop a plan — key ideas, style guide, outline, template, and page layout.

1. How To Do It

List your key ideas, then rank them by what the reader needs first — not by what came first in your research.
Write your headings as the questions your reader would actually ask.
Set a short style guide: a handful of rules you’ll follow every time.
Choose a template and sketch the page layout before drafting.
Decide where each piece goes on the page, and how much room it gets.

2. Marisol’s Project

Key ideas, ranked: thirty-one candidate steps. Here the reader’s need is chronological, so the visit’s own order is the ranking — grouped into four phases.
Headings as questions: Patient walks in — what now? beats “Phase One: Intake,” because nobody has ever asked the second one.
Style guide: imperative verb first, one action per line, eight words max, use the software’s own field names, flag legally required steps with a symbol.
Layout sketch: checkbox column down the left, four labeled blocks, the three failure-prone steps boxed at the bottom. Single-sided — the desk tray shows one face.
Room: the sketch allows about sixteen steps. She has thirty-one. Cutting fifteen is now a structural problem, solved before drafting rather than discovered during it.

3. Key Insights

There are hard numbers on how much a reader will hold, and they should set your budget. Gawande’s research on working checklists lands on five to nine items per pause point — roughly the limit of working memory — and about sixty to ninety seconds before people start shortcutting and skipping steps. Marisol’s sixteen steps across four blocks fits inside that. Thirty-one would not have, no matter how good the wording was.
Readers scan; they don’t read. Jakob Nielsen’s measurements put it at roughly twenty percent of the words on a page. That’s the whole argument for headings written as reader questions: a scanner isn’t reading your document, they’re hunting for their question, and “Phase One: Intake” isn’t a question anyone has.
Sketching the layout converts your page into a word budget. Writers who skip this reliably produce twice the text that will fit, then try to solve a design problem with cutting — which is the hardest and latest possible place to solve it.
Easily missed: decide whether you’re ordering by urgency or by sequence. Most documents should lead with what the reader needs most. But when the document’s whole job is a sequence, chronology is the urgency. Getting this backwards produces either a buried warning or a set of steps in the wrong order.

WRITE

DEFINITION: Create a detailed working draft. Iterate as necessary.

1. How To Do It

Draft into the structure you built. Don’t restructure while you’re drafting.
Write the sections in any order. Start with whichever one you understand best.
Keep it to one idea per sentence and one action per step.
Get the content down first; cut jargon and tighten on a later pass.
Expect several passes. A working draft is supposed to be rough.

2. Marisol’s Project

She drafts into the four blocks. Twice she wants to add a fifth for phone check-ins; both times she parks the idea on a separate list and keeps going.
She writes Before you seat them first because she does it twenty times a day, and the departure block last because she understands it least.
One action per line: “greet, confirm date of birth, pull the chart” becomes three lines with three checkboxes.
Her first pass gets all thirty-one steps down and reads badly. She leaves it that way — content first, polish later.
Two more passes get her to sixteen. The cuts come from her research: duplicate insurance checks merged, four local-habit steps deleted.

3. Key Insights

The rough first draft isn’t a failure state, it’s the method. Anne Lamott made the point permanent in Bird by Bird: almost nobody produces good prose on the first pass, and the writers who appear to are the ones who’ve stopped showing you their early drafts. A first draft that already reads well usually means you spent your time polishing instead of thinking.
Cut to the action. Carroll’s minimalist manuals at IBM stripped documentation down to what the user was trying to do — chapters averaging three pages against commercial manuals many times longer. Learners using them were substantially faster and learned at least as much. Length is not thoroughness.
Easily missed: redundancy only becomes visible once it’s written down. When you record everything a process currently involves, you will find the same task being done twice under two different names by two different people. Nobody notices this while doing the work. It only shows up on the page.
If drafting exposes a structural problem, go back to Step 3. Patching a broken structure with transitions and cross-references never works, and the repair costs less now than it will after you’ve added graphics to it.

5	INTEGRATE DATA & GRAPHICS

DEFINITION: Create and/or integrate tables, charts, screenshots, and diagrams as required.

1. How To Do It

Find the passages doing work a visual could do better: procedures, comparisons, and numbers.
Choose the right form — a diagram for a process, a table for comparison, a chart for trends, a screenshot for software.
Label everything. A graphic should make sense to someone who hasn’t read the prose around it.
Delete the prose the graphic replaced. Adding without cutting makes the document longer, not clearer.
Check that it still works in black and white, and at the size it will actually be printed.

2. Marisol’s Project

Two passages are doing visual work badly: five lines splitting new versus returning patients, and two lines describing where a software field lives.
The split becomes a two-column table; the field becomes a cropped screenshot with a callout. She drops a flowchart idea — the checkboxes already carry sequence, and you can’t mark a flowchart.
Both get labeled to stand alone. The screenshot’s callout reads update this field first.
She deletes the seven lines the graphics replaced. Without that cut, two graphics would have pushed an already-full page over.
Printing reveals what the screen hid: the flags lose their color in black and white, so she adds an outline and a symbol.

3. Key Insights

Decoration displaces information. Edward Tufte’s term for the ornament that creeps into charts is chartjunk, and his standard is unforgiving: the ink on the page should be carrying data. Every gradient, frame, and clip-art icon is occupying space some actual content wanted.
Match the form to the job. Diagrams for processes, tables for comparisons, charts for trends, screenshots for software. Choosing the wrong form is far more common than including no graphic at all — and a flowchart that can’t be marked is useless to a reader tracking their own progress.
Adding a visual without deleting what it replaced makes the document worse. You’ve now got the same content twice, on a page that was already full. The deletion isn’t cleanup after the step; it is the step.
Easily missed: your document will be photocopied. Gawande’s guidance on checklist design is blunt about unnecessary color, and for good reason — workplace documents get faxed, photocopied, printed in grayscale, and read by people who don’t distinguish red from green. Anything color alone is carrying will be lost.

6	REVIEW & REVISE

DEFINITION: Receive feedback from readers, then revise, finalize, and submit your final draft.

1. How To Do It

Put the draft in front of a real reader from your audience — not a friend who will be nice about it.
Give them a task instead of a question. Ask them to find something or do something.
Watch where they hesitate, backtrack, or guess. Note it without helping them.
Get a peer review for the problems you can’t see because you wrote it.
Fix the largest problems first. Save proofreading for the very end, then finalize and submit.

2. Marisol’s Project

She tests it on Devin — the reader she named in Step 1 — not on the office manager, who knows the process too well to stumble.
She gives him a task, not a question: check in the next three patients using only this sheet.
He stalls twice, and she says nothing. Verify coverage doesn’t say whether to call or check the portal, and he reads both table columns before realizing only one applies.
A classmate’s peer review catches what she’d stopped seeing: the next-appointment step sits below where the sheet folds into the tray.
Big fixes first — name the portal, label the table, move and box the next-appointment step. Proofreading comes last.

3. Key Insights

Give a task, not a question. Steve Krug built a whole practice on this: hand someone a real job to do, then stay neutral, ask nothing leading, and offer no help. “Does this make sense?” produces a polite yes. “Check in the next three patients using only this” produces evidence.
The moment you help, the test is over. Every hesitation is a defect report — a pause, a backtrack, a guess — and it stops being data the instant you explain. This is the hardest part of testing your own work, and the part most people fail.
Test earlier and rougher than feels reasonable. Krug’s point is that you can test a sketch on a napkin, and that a small amount of testing beats an unlimited amount of arguing about what users will probably do. Gawande puts the same rule more sharply: if the people who have to use it didn’t help build it, what you have is still a draft.
Easily missed: fix the biggest problems, not all of them. Krug’s advice is to make the smallest change that solves the real problem rather than launching a redesign. Marisol didn’t rebuild her checklist — she renamed one step, added one line, and moved one box. Then she proofread, because proofreading text you might still delete is wasted work.

Where This Goes Next

The process is the point — but it isn’t a cage.

Six numbered steps look rigid on a page like this one. In practice they aren’t. Marisol went back to her structure while she was drafting. She cut steps in Step 4 that her research had flagged in Step 2. Her page sketch decided her word count before she wrote a sentence, and her test reader sent her back to rewrite a heading she thought was finished. The steps run forward, but the work loops.

What doesn’t change is that each step depends on the ones before it. Skip the analysis and your research gathers the wrong information. Skip the structure and your draft has nowhere to go. Skip the review and you never learn that your document failed the one reader who needed it. You can move between steps freely. You can’t skip one and expect the next to hold.

Expect the process to feel mechanical the first time through. That’s normal, and it’s temporary. What experienced writers describe is that the steps stop feeling like a checklist and start feeling like a single motion — you find yourself thinking about layout while you’re still doing research, or hearing your test reader’s questions while you draft. The steps are teaching you to hold the whole document in mind at once. That’s the part that adds up to more than the six pieces.

In the first half of this semester we’ll take the steps one at a time and practice each on its own. In the second half, you’ll run all six yourself — on a project in your own field, for readers of your own choosing — and start adapting them to the way you actually work.

Sources & Further Reading

Everything cited in the Key Insights above, if you want to go to the originals.

Course introduction video — assigned viewing, linked at the top of this page.
Janice (Ginny) Redish, Letting Go of the Words: Writing Web Content that Works — the standard work on writing to a reader’s purpose. Cited in Step 1.
John M. Carroll and Mary Beth Rosson, “Paradox of the Active User” (full chapter, PDF) — the original IBM research on why people don’t read the manual. A shorter summary from Nielsen Norman Group is easier going. Cited in Steps 1 and 4.
Atul Gawande, The Checklist Manifesto: How to Get Things Right (Metropolitan Books, 2009) — where the five-to-nine rule and the “killer items” idea come from. Gawande discusses the underlying WHO research in this NPR interview. Cited in Steps 2, 3, 5, and 6.
Jakob Nielsen, “How Little Do Users Read?” — the measurement behind the twenty percent figure. Cited in Step 3.
Anne Lamott, Bird by Bird: Some Instructions on Writing and Life (Anchor, 1994) — on rough first drafts. Cited in Step 4.
Edward R. Tufte, The Visual Display of Quantitative Information, 2nd ed. (Graphics Press, 2001) — the source of “chartjunk” and the data-ink ratio. Cited in Step 5.
Steve Krug, Don’t Make Me Think and Rocket Surgery Made Easy (New Riders) — do-it-yourself usability testing, including the task-not-question rule. Cited in Step 6.