Technical & Professional Writing

Two numbers that did not match

On 23 September 1999 the Mars Climate Orbiter fired its main engine to enter orbit around Mars and was never heard from again. The spacecraft was healthy. The propulsion worked. What failed was a document. Ground software reported the impulse of small thruster firings in pound-force seconds. The navigation software that consumed those numbers expected newton-seconds, a unit roughly four and a half times larger. Nobody converted, and across nine and a half months of cruise the discrepancy accumulated into a navigation error. NASA had planned to bring the orbiter around Mars at an altitude of 226 kilometres. Roughly 80 kilometres was the lowest it was thought able to survive. Reconstruction after the loss put its actual path within about 57 kilometres of the surface.

The Mishap Investigation Board did not conclude that someone had done bad arithmetic. It concluded that the interface between two teams had not been specified in a way that made the units unmissable. That is a writing failure with a spacecraft attached to it. It is also the cleanest available illustration of the claim this course rests on: technical writing is not decoration applied after the engineering is done. On any project of consequence, it is part of the engineering.

The only definition that does any work

Textbooks like to define technical writing by subject: writing about technology, science, medicine, or industry. That definition is useless, because it would exclude a beautifully written set of instructions for folding a paper crane and include a bad poem about a centrifuge. Here is a definition you can actually use: technical writing is writing whose success is measured by whether a particular reader can do a particular thing.

Everything follows from that. If the reader cannot complete the task, the document failed, and it does not matter that the grammar was clean, the tone was professional, or the author found the topic interesting. Conversely, a document that reads like a shopping list has succeeded completely if the reader assembled the shelf, filed the claim, called the right API endpoint, or evacuated the building. Notice what this definition demands of you before you write anything: you have to know who the reader is and what the reader is trying to do. Guessing at both is the single most common cause of documents that nobody uses.

The point: Technical writing is judged by reader performance, not by author performance. The question is never "is this good writing," it is "did this reader succeed."

What the essay taught you, and what to unlearn

If you have written college essays, you have been trained by a reader unlike any you will meet at work. Your instructor was paid to read every word, in order, once, at a desk, with no competing demands, and was looking for evidence that you had thought carefully. Almost none of that describes the person who will open your next document. Here is the shift, dimension by dimension.

Dimension	Academic essay	Technical document
Purpose	Demonstrate your thinking to an evaluator	Enable a reader to decide or act
Reader	An expert obliged to finish it	A busy non-specialist who will read the minimum
Reading pattern	Front to back, once	Scanned, out of order, under time pressure, often more than once
Placement of the point	Built toward, sometimes revealed at the end	First sentence, then supported
Length	A target to reach	A cost to minimize
Voice	Individual and distinctive	Consistent and unobtrusive, matched to a house style
Repeating a term	Monotonous; find a synonym	Correct; the same object gets the same name every time
Visual design	Mostly irrelevant to the argument	Part of the argument; headings and tables carry meaning
Test of success	A grade	The reader completed the task, or did not

The row about synonyms surprises people most. English teachers warn against repeating a word too often, and in an essay that advice is sound. In a technical document it is dangerous. If the button is labelled Submit, call it Submit every time. Calling it "the send control" in paragraph two and "the confirm button" in paragraph four does not add elegance; it invents two objects that do not exist and sends the reader looking for them.

Almost nobody reads your document

In usability research reported by Jakob Nielsen in 1997, 79 percent of test users always scanned any new page they encountered, and only 16 percent read word by word. That study was about web pages, but the behaviour it describes is now the default for nearly every workplace document, including the PDF attached to an email at 4:50 on a Friday. Readers arrive with a question, hunt for the answer, take it, and leave.

This is not laziness, and you do it too. It means your document has two jobs, not one. It has to contain the right answer, and it has to make the right answer findable by someone who never reads the paragraph above it. A document that would be perfectly clear if read start to finish, and is useless when sampled, has failed by the standard that matters. Headings, lists, tables, and a first sentence that states the conclusion are not stylistic flourishes. They are the retrieval system.

Key idea: Write for a reader who enters in the middle, takes one piece, and leaves. Structure is how they find the piece.

One rewrite, six named changes

Here is a sentence in the register that institutions fall into naturally. Read it once at normal speed and see whether you can state what the reader is supposed to do.

Before: "Please be advised that submission of the aforementioned documentation is required to be effectuated by all applicants prior to the expiration of the thirty (30) day period commencing on the date of this notice, and failure to effectuate such submission may result in the discontinuation of processing of the application in question."

After: "Send us the documents listed above within 30 days of the date on this letter. If you do not, we will stop processing your application."

Fifty-five words become twenty-six, and the twenty-six carry more information because they name who acts. Six specific changes did the work, and you can apply each of them by hand:

1. Address the reader. "All applicants" became "you." The reader no longer has to work out whether the rule applies to them.
2. Turn nouns back into verbs. "Submission ... is required to be effectuated" became "send." A buried verb wearing a noun costume is called a nominalization, and hunting them is the highest-yield edit in this course.
3. Use active voice with a named actor. "May result in the discontinuation" hides who stops. "We will stop" names the agency.
4. Delete the throat-clearing. "Please be advised that" and "in question" carry no content.
5. Cut redundant legalisms. "Thirty (30)" is a habit from handwritten contracts. "Prior to the expiration of the thirty day period commencing on the date of this notice" is a long way to say "within 30 days of the date on this letter."
6. Put the consequence in its own sentence. One sentence with a condition inside a condition becomes two sentences the reader can hold.

Notice what the rewrite did not do. It did not soften the requirement, drop the deadline, or make a promise the original avoided. Plain language is not the same as vague language. The plainer version is legally tighter, because "we will stop processing your application" is a specific claim about a specific actor, while "may result in the discontinuation of processing" leaves everything undecided.

The genres you will actually write

Technical writing is a family of genres, and each has conventions that readers already know. Learning the conventions is most of the work, because a document that behaves the way its readers expect requires no explanation of itself. This course walks through the ones you are most likely to need: instructions and procedures, software and API reference, formal reports, white papers, proposals, workplace correspondence, and the presentation of data. Alongside those sit skills that cut across every genre, such as document design, accessibility, editing to a style guide, collaborating in version control, and writing for readers who will receive your words through a translator.

Two things are worth saying about the job market for this, because students ask. First, the Bureau of Labor Statistics tracks technical writers as a distinct occupation in its Occupational Outlook Handbook, with typical entry requiring a bachelor's degree and subject-matter familiarity. Second, and more important, most technical writing is not done by people with that job title. It is done by engineers writing design documents, nurses writing care instructions, analysts writing memos, and developers writing the README that decides whether anyone adopts their library. Miriam Kimball has argued that technical communication is now in a period she calls extra-institutional, produced by enormous numbers of people who never trained for it and never call themselves writers. That is the realistic case for taking this seriously even if you plan to be something else.

Worth holding on to: You will write technical documents in whatever career you choose. The only question is whether you will write them well enough that people can use them.

Common misconceptions

• Technical writing means writing about technology. It means writing that lets a reader act. A recipe and a benefits notice are technical writing; a magazine feature about a data centre is not.
• Plain language means dumbing down. The rewrite above is more precise, not less. Simplifying the sentence forced the writer to commit to who does what.
• Good technical writing is a matter of grammar. Grammar is the floor. A grammatically flawless document that buries the deadline in paragraph nine has failed.
• Shorter is always better. Shorter is better only when nothing the reader needs was removed. A warning that is cut for brevity is not concise, it is incomplete.
• Repeating a term is bad style. In technical prose, one object gets one name. Elegant variation creates phantom objects.
• The writing happens at the end, once the real work is done. The Mars Climate Orbiter interface specification was the real work.

What to carry forward

• Technical writing is judged by whether a named reader can do a named thing, not by whether the prose impresses.
• The essay reader is obliged, patient, and linear. The workplace reader is none of those, so structure carries as much weight as sentences.
• Most readers scan, so the point goes first and headings, lists, and tables do the retrieval work.
• Six repeatable edits do most of the work of plain language: address the reader, unbury verbs, use active voice with a named actor, delete throat-clearing, cut legalisms, split stacked conditions.
• Plain language increases precision by forcing you to say who does what to whom.
• Genre conventions are not arbitrary. A document that behaves as its readers expect needs no instructions for reading it.

Sources

1. NASA Mars Climate Orbiter Mishap Investigation Board. (1999). Phase I report. National Aeronautics and Space Administration. Mission summary and failure account: science.nasa.gov and Mars Climate Orbiter
2. Nielsen, J. (1997). How users read on the web. Nielsen Norman Group. nngroup.com
3. Kimball, M. A. (2017). The golden age of technical communication. Journal of Technical Writing and Communication, 47(3), 330-358. doi.org/10.1177/0047281616641927
4. U.S. Bureau of Labor Statistics. Technical writers. Occupational Outlook Handbook. bls.gov

Two forms became one

Before 3 October 2015, an American applying for a home loan received two separate disclosures within days of applying: a Good Faith Estimate required by one statute and an initial Truth in Lending disclosure required by another. The two forms had been written by different agencies at different times, overlapped in places, contradicted each other in emphasis, and used different words for the same dollar amounts. On that date the Consumer Financial Protection Bureau replaced both with a single three-page Loan Estimate, and replaced the closing paperwork with a five-page Closing Disclosure that has to reach the borrower at least three business days before signing.

The bureau did not design those forms by asking lawyers what had to be disclosed. It started from a question about a reader: what does a person deciding whether to take on thirty years of debt need to see, in what order, to compare one offer with another? Draft forms went in front of consumers and lenders through rounds of testing, and the layout changed in response to what testers could and could not find. The interesting part is the three-day rule. It is not a writing rule at all. It is a recognition that a document read under pressure at a closing table is a different document from the same words read at a kitchen table on a Tuesday. Conditions of reading are part of audience analysis.

Five questions that make a reader profile

Audience analysis has a bad reputation among students because it is often taught as demographics. Age, education, income. Those are almost useless. What you need are five answers, and you can usually get them in a fifteen-minute conversation with someone who has the job you are writing for.

1. Who is the reader, by role? Not "the public" but "a night-shift charge nurse", "a procurement officer comparing three bids", "a backend developer integrating our payment API for the first time."
2. What is the reader trying to do? The task, stated as a verb with an object. Not "learn about the system" but "reset a locked account without calling the help desk."
3. What does the reader already know? Which terms land, which need defining, and which will be misread because the reader knows a different meaning for them.
4. What decision or action does this document have to support? If nothing changes as a result of reading it, the document has no purpose and should not exist.
5. Under what conditions will it be read? On a phone, in a server room at 3 a.m., with gloves on, with a supervisor waiting, in a second language, after a bad night. This question changes documents more than any other, and it is the one most often skipped.

Why this matters: A reader profile is a set of constraints. Constraints are what let you cut. Without them, every paragraph seems arguably useful, and the document grows until nobody reads it.

The curse of knowledge, measured

The reason audience analysis has to be deliberate is that your own expertise actively distorts your estimate of what other people know. In a 1990 Stanford study, Elizabeth Newton had participants tap the rhythm of a well-known song on a table while a listener tried to name it. Before each trial the tappers predicted how often listeners would succeed. They predicted about half. Listeners identified roughly one song in forty. The tappers could hear the melody in their heads and could not imagine the bare taps the listener actually received.

Economists gave this its name. Camerer, Loewenstein and Weber, writing in the Journal of Political Economy in 1989, showed that better informed agents could not properly discount their private information when predicting the judgments of less informed agents. The effect is not stupidity or arrogance. It is that knowledge, once acquired, becomes invisible to the person holding it. When you write "simply configure the endpoint", you are hearing the melody. Your reader is getting taps.

There is only one reliable cure, and it is not thinking harder. It is contact with an actual reader: watching someone use your draft, or at minimum having someone in the target role read it and mark every place they stopped.

Worked example: one change, two documents

A hospital is turning on multi-factor authentication for its clinical record system. The engineering facts are identical for everyone. Watch what happens when the reader changes.

Reader A: the systems administrators. Role: six people who will configure and support the rollout. Task: deploy the change without breaking overnight batch jobs. Prior knowledge: high, including the identity provider and the existing single sign-on. Decision supported: how to sequence the rollout and what to do when it fails. Conditions: at a desk, with two screens, able to read carefully.

Their document is a runbook. It opens with the change window and the rollback command. It uses exact configuration keys, states which service accounts are exempt and why, lists the four known failure modes with their log signatures, and links to the vendor reference. It can be long, because they will read it in sequence while doing the work.

Reader B: the ward nurses. Role: about four hundred clinical staff. Task: log in and get to a patient chart. Prior knowledge: they use the system constantly and know nothing about identity providers. Decision supported: none, really. They have no choice; they need to get in. Conditions: badging in at 06:55 at a shared workstation, sometimes gloved, with a handover starting, and personal phones often not permitted on the floor.

Their document is not a shorter runbook. It is a different genre. It answers three questions in this order: what will look different when I log in on Monday, what do I type, and what do I do if the code does not arrive. It fits on one side of a card taped beside the workstation. It never uses the phrase multi-factor authentication, because that phrase does not help anyone log in. And it opens with the single sentence the writer of the runbook would never think to write: "Your badge alone will no longer log you in."

In short: Same facts, same week, same system. Different reader, different task, different reading conditions, therefore a different document. Not a summary of the other one.

The readers you did not think of

Almost every workplace document has more than one audience, and the extra ones have real power over whether it works. Technical communication traditionally names three layers beyond the primary reader.

Audience	Who they are	What they need from you
Primary	The person who acts on the document	The task, findable and correct
Secondary	People affected by the action: a supervisor, a downstream team	Enough context to see how the action fits
Gatekeeper	Whoever must approve it before it reaches the primary reader: a manager, legal, a security review	Assurance that nothing here creates a risk they will be blamed for
Tertiary and future	Auditors, translators, and the person who inherits this in three years	Dates, versions, sources, definitions, and prose that survives translation

The gatekeeper is the one students underestimate. A brilliantly clear document that a compliance officer will not sign never reaches anyone. Writing for the gatekeeper does not mean writing badly; usually it means naming the risk explicitly somewhere the gatekeeper will look, so that they do not have to invent a worse sentence to cover it.

The purpose statement, and what it lets you delete

Before drafting, write one sentence in this shape: After reading this, [reader] will be able to [do what], so that [why it matters to them]. For the nurses above: "After reading this card, a nurse arriving for a shift will be able to complete the new login on the first attempt, so that the shift starts on time."

Now use it as a knife. Does the history of the security review serve that sentence? No. Cut it. Does the vendor's product name serve it? No. Cut it. Does the phone number for the help desk serve it? Yes, and it should be large. A purpose statement is worth writing precisely because it makes deletion arguable rather than personal. When a colleague insists on adding a paragraph about the project's governance, you are no longer saying you dislike it; you are asking which reader task it serves.

General purposes come in four kinds, and mixing them silently is a common defect. A document may instruct (do this), inform (know this), persuade (agree to this), or record (this is what happened, for later). A page that tries to instruct and persuade at once tends to do neither: the reader trying to act has to wade through the argument, and the reader deciding has to wade through the steps.

The core of it: Purpose is not a topic. It is a change in a specific reader's state, and if you cannot name that change, no amount of good sentences will rescue the document.

Common misconceptions

• Audience analysis means demographics. Role, task, prior knowledge, decision, and reading conditions do the work. Age and income almost never do.
• If I write for the least expert reader, everyone is served. Not so. A runbook stripped to the nurses' level would leave the administrators unable to do the deployment. Serve the primary reader, then decide what the others need.
• Writing for a non-expert means leaving things out. It means changing what is explained, not reducing the accuracy of what remains.
• I know my readers; I am one of them. You were one of them before you learned the system. The tapping study is about exactly this gap.
• Purpose is the subject of the document. Purpose is what the reader will be able to do afterwards. "About the new login policy" is a subject, not a purpose.

Putting it together

• A reader profile answers five questions: who by role, doing what task, knowing what already, deciding what, under what conditions.
• Reading conditions change documents more than any other factor and are the factor most often ignored.
• The curse of knowledge is measurable and does not respond to effort. It responds to contact with a real reader.
• Different audiences for the same facts need different genres, not longer and shorter versions of one document.
• Gatekeepers decide whether the primary reader ever sees your work, so write the sentence that lets them approve it.
• A purpose statement of the form "after reading this, X will be able to Y, so that Z" turns cutting from a matter of taste into a matter of evidence.

Sources

1. Consumer Financial Protection Bureau. Loan Estimate: What it is and how to use it. consumerfinance.gov
2. Camerer, C., Loewenstein, G., and Weber, M. (1989). The curse of knowledge in economic settings: An experimental analysis. Journal of Political Economy, 97(5), 1232-1254. doi.org/10.1086/261651
3. Digital.gov. Principles of plain language. U.S. General Services Administration. digital.gov
4. Morkes, J., and Nielsen, J. (1997). Concise, scannable, and objective: How to write for the web. Nielsen Norman Group. nngroup.com

A law about sentences

On 13 October 2010 the Plain Writing Act became law in the United States. Its stated purpose is to improve the effectiveness and accountability of federal agencies by promoting clear government communication that the public can understand and use. Every covered agency has to use plain writing in documents that explain a benefit or service, tell people how to comply with a requirement, or file taxes. Agencies must train staff, designate a senior official for plain writing, and report on compliance.

Congress had form here. In 1998 the Securities and Exchange Commission had already required the front sections of a prospectus to be written in plain English, after decades in which disclosure documents were technically complete and practically unreadable. Warren Buffett, writing the preface to the commission's handbook on the subject, described his own method as picturing a particular reader, someone intelligent but not immersed in finance, and writing to that person. That is the whole idea in one move, and the rest of this lesson is the mechanics.

Twelve techniques, each with a before and an after

Read the left column at normal speed, then the right. The point is not that the right column is prettier. It is that you can execute each of these changes deliberately, on demand, and say afterwards which one you used.

Technique	Before	After
1. Address the reader	Applicants must provide proof of residency.	You must send us proof that you live here.
2. Active voice, named actor	The application will be reviewed within 10 days.	We will review your application within 10 days.
3. Unbury the verb	Completion of the form is a requirement for the initiation of processing.	Complete the form so we can start processing.
4. Common words	Utilize the enclosed envelope to effectuate transmission.	Use the envelope we sent.
5. Split stacked conditions	If you are self-employed and did not file a return, unless exempt under section 4, you must attach a statement.	Attach a statement if both of these are true: you are self-employed, and you did not file a return. You do not need to if section 4 exempts you.
6. Use must, not shall	The contractor shall maintain records.	The contractor must keep records.
7. Break noun stacks	Employee benefit eligibility determination procedures	How we decide whether you can get benefits
8. Main clause first	In accordance with the policy adopted in March, and subject to available funding, travel will be reimbursed.	We will reimburse your travel. This follows the March policy and depends on available funding.
9. Turn conditions into a list	You qualify if you are over 65, or disabled, or a veteran with a service-connected condition.	You qualify if any one of these applies to you: you are 65 or older; you are disabled; you are a veteran with a service-connected condition.
10. Concrete numbers	Submit the report in a timely manner.	Send the report by 5 p.m. on 30 June.
11. Say what to do	Do not submit incomplete forms.	Fill in every box marked required, then send the form.
12. One term, used consistently	Upload the file, then confirm the document has been received; the record will appear in your queue.	Upload the file, then check that the file appears in your queue.

Technique 6 deserves a note, because it looks like pedantry and is not. "Shall" has been used in legal drafting to mean an obligation, a prediction, a permission, and a definition, sometimes in the same document. Courts have spent real money resolving which was meant. "Must" carries obligation and nothing else, which is why plain language guidance in several countries now prefers it.

Bottom line: Plain language is not a mood. It is a set of about a dozen operations that you can name, apply, and check afterwards.

A longer rewrite, worked

Techniques are easier to admire than to use, so here is a paragraph of the kind that arrives from an insurer. Read it and try to answer one question: if you had a car accident last Tuesday, by when must you do what?

Before: "Notification to the Company of any occurrence which may give rise to a claim under this policy is required to be made by the insured as soon as practicable following such occurrence, and in no event later than thirty (30) days thereafter, and failure to provide such notification within the aforementioned period may, at the discretion of the Company, result in the denial of coverage with respect to the occurrence in question, provided that the Company may waive this requirement where the insured can demonstrate that such notification was not reasonably possible."

After:

"Tell us about an accident within 30 days.

If you have an accident that might lead to a claim, call us as soon as you can, and no later than 30 days after it happens. If you tell us later than that, we may refuse to cover the accident. If you could not reasonably have told us in time, explain why, and we may still cover it."

Eighty-six words become fifty-eight, and the deadline moved from the middle of the sentence to the first line, where a frightened reader will find it. Look at which techniques did the work: address the reader (1), active voice with a named actor (2), unbury "notification" into "tell us" (3), common words (4), split the stacked conditions (5), main clause first (8), concrete number in the heading (10). Seven of the twelve, in one paragraph.

Notice one thing the rewrite kept. The original said coverage "may" be denied at the company's discretion, and the rewrite says "we may refuse", not "we will refuse". Rewriting is not licence to resolve an ambiguity in the reader's favour. If the original is deliberately hedged, the plain version stays hedged, and says plainly that it is hedged.

What readability formulas can and cannot tell you

Rudolf Flesch published his reading ease formula in the Journal of Applied Psychology in 1948, and a version adapted for the U.S. Navy in the 1970s produced the grade level scores now built into word processors. These formulas are useful and badly misused, so it is worth being precise about what they do. They count syllables per word and words per sentence. That is all. They have no access to whether a sentence is logically ordered, whether a term is defined before use, whether the reader can find the deadline, or whether the document is true.

Two consequences follow. First, a good score does not mean a clear document. "The party of the first part shall not be deemed to have waived any right not herein expressly waived" is short in words and syllables and nearly meaningless. Second, a bad score can be a false alarm: a document written for cardiologists will score badly because "echocardiography" has six syllables, and replacing it would make the document worse.

Use the formulas as a smoke alarm, not as a grade. If a passage aimed at the general public scores at a graduate reading level, something is probably wrong and you should look. But the real test is the one federal plain language guidance recommends and this course keeps returning to: give the document to someone in the target audience and watch what they can do with it.

Remember: A readability score measures word length and sentence length. It does not measure whether anyone understood anything.

When jargon stays

Plain language is not the removal of technical terms. If your readers are anaesthetists, write "propofol", not "the white sleepy medicine". Precision is the point of the vocabulary, and paraphrasing it costs accuracy and insults the reader. The rule is about the match between term and audience, not about the term itself.

Three practical tests. Does the reader use this word in their own work? Keep it. Does the reader need this word to look something up later, in a manual or a regulation or an error log? Keep it, and define it on first use. Is the word doing no work that a common word could not do, and is it there mostly because it sounds professional? That is the one to cut. "Utilize" fails all three tests. "Anticoagulant" passes the first two in a clinical document and fails them in a leaflet for patients, where "medicine that stops your blood clotting" is more accurate for that reader, not less.

So what?: The question is never "is this word too hard." It is "does this reader already own this word, or need to."

Common misconceptions

• Plain language means short documents. Sometimes it means longer ones. Adding the missing subject, an example, or a worked case costs words and buys comprehension.
• Plain language is for the general public only. Engineers and lawyers read scanned, tired, and under deadline like everyone else. Internal documents benefit most, because nobody proofreads them.
• A good readability score means the writing is clear. The formula counts syllables and sentence length. It cannot detect a missing definition or a buried deadline.
• Removing jargon always helps. Removing a term your reader uses daily makes the document less precise and slower to use.
• Plain language weakens legal documents. The plain version of the insurance clause preserved every hedge and every condition. It simply put them where a reader could find them.
• Using "shall" makes writing sound official and therefore binding. It has meant so many different things that drafters increasingly replace it with "must".

The short version

• The Plain Writing Act of 2010 makes clear writing a legal obligation for U.S. federal agencies in a wide class of public documents.
• Twelve named techniques cover most of what plain language rewriting actually involves, and you should be able to name the one you used.
• Reordering matters as much as rewording: the deadline belongs in the first line, not the middle of a subordinate clause.
• A rewrite must preserve every condition, hedge, and obligation in the original. Clarity gained by dropping a requirement is falsification.
• Readability formulas measure word and sentence length only. Treat a bad score as a prompt to look, never as a verdict.
• Keep the technical term when the reader owns it or needs it to look something up. Cut it when it is there to sound professional.

Sources

1. Plain Writing Act of 2010, Pub. L. No. 111-274. congress.gov
2. Digital.gov. Writing for understanding: clear and short. U.S. General Services Administration. digital.gov
3. PlainLanguage.gov. Federal plain language guidelines. plainlanguage.gov
4. Flesch, R. (1948). A new readability yardstick. Journal of Applied Psychology, 32(3), 221-233. doi.org/10.1037/h0057532

The same content, five ways

In 1997 John Morkes and Jakob Nielsen took one web page of tourist information about Nebraska and rewrote it four times. One version was concise, with about half the word count. One was scannable: the same words, but broken with bulleted lists, highlighted keywords and meaningful subheadings. One replaced promotional language with neutral, objective wording. One combined all three. Then they measured how well people could use each version.

Against the control, the scannable version measured 47 percent better, the concise version 58 percent better, and the objective version 27 percent better. The combined version measured 124 percent better. Read that again with an eye on what changed: in the scannable version, not one fact was added or removed. Only the shape of the page changed, and usability nearly halved the difficulty. Design is not what you do to a document after the writing. On a page that will be scanned, design is a large fraction of the writing.

What scanning actually looks like

Nielsen's earlier work had already found that 79 percent of test users always scanned a new page and only 16 percent read word by word. Later eye-tracking work at the same group described a common pattern on text-heavy pages: readers sweep across the top, sweep across again a little lower and less far, then run their eyes down the left edge, producing a rough letter F. The F is not a law of nature, and it shows up most on pages that offer no structure to grab. That is exactly the point. The F is what reading looks like when a page gives the eye nothing better to do.

Three consequences follow, and they are the whole design brief. First, the top of the page and the first two words of every line and heading are expensive real estate; spend them on content, not on throat-clearing. Second, anything that only appears in the middle of a long paragraph is, for practical purposes, invisible. Third, structure is not a courtesy to lazy readers. It is the only mechanism by which a reader who enters at an arbitrary point can orient themselves.

What matters here: You cannot make people read. You can make the thing they need findable in the four seconds they will give you.

Headings that answer a question

Most weak documents have headings, and the headings are the problem. Compare two tables of contents for the same engineering report.

Label headings	Descriptive headings
Introduction	Why we stopped the pilot line on 14 March
Background	The axle redesign and what changed in the tolerance
Methodology	How we tested 40 axles to failure
Analysis	Why the axle failed the stiffness check
Discussion	Two explanations, and why the supplier change fits better
Recommendations	Return to the 2024 supplier before the June build

The left column names slots. The right column tells the story, and a reader who reads nothing else already knows the finding and the recommendation. Descriptive headings cost more to write, because you cannot write one until you know what the section concludes. That difficulty is a feature; it catches sections that have no point.

A related rule: headings must be a real hierarchy, not a set of font sizes. If a level-three heading appears under a level-one heading with no level two in between, the outline has a hole, and any tool that builds a table of contents or navigates by heading will reproduce the hole. Skipping a level to get a smaller font is one of the most common structural defects in workplace documents.

Chunking, and the paragraph as a retrieval unit

In a document that will be scanned, a paragraph is not a unit of thought. It is a unit of retrieval. That means one idea per paragraph, announced in the first sentence, and paragraphs short enough that a reader can tell from the first line whether to read the rest. Six lines is a reasonable ceiling for prose that a reader may sample; eight is pushing it.

The related move is converting prose into a list when the content is a list. A sentence containing three "and"s and two "or"s is usually a set of items pretending to be a sentence. But two cautions apply. A list of items that have no parallel structure reads worse than the paragraph it replaced, because the reader keeps looking for the pattern. And a document that is all bullets has lost the ability to state a relationship, since bullets flatten cause, sequence, and contrast into a single visual level. Bullets for parallel items, prose for reasoning about them.

When a table beats both

Here is a rule you can apply mechanically. If your content has two dimensions, it belongs in a table. Three plans compared across four features is a table with three rows and four columns, and no amount of skilled prose will let a reader compare plan two with plan three as fast as their eye can move across a row.

Test this on yourself. "The standard plan includes 24-hour support and two seats but no audit log, while the team plan adds the audit log and five seats and keeps 24-hour support, and the enterprise plan has all of these plus a dedicated contact." Now the table.

Feature	Standard	Team	Enterprise
Seats	2	5	Unlimited
24-hour support	Yes	Yes	Yes
Audit log	No	Yes	Yes
Dedicated contact	No	No	Yes

The table also exposed something the paragraph hid: the paragraph never said how many seats the enterprise plan has. Prose lets you skip a cell. A table shows the hole.

The upshot: Turn prose into a table whenever the content varies along two dimensions. The conversion is also an audit, because empty cells are missing facts.

Information architecture: choosing an order

Information architecture is the arrangement of a whole document or documentation set, and the choice of pattern should come from what the reader is doing, not from how the organization is arranged. The common patterns and their fit:

• Task order. Organized by what the reader wants to accomplish. The default for anything instructional, and almost always right for user documentation.
• Chronological. For incident reports, project histories, and anything where sequence is the content.
• General to specific. For explanatory documents where the reader needs a frame before the detail.
• Spatial. For hardware, facilities, and anything a reader navigates physically.
• Alphabetical. For reference material a reader arrives at already knowing the term, such as a glossary or an API index. Terrible for anything a reader must be taught.
• Comparison. When the reader's task is to choose between options.

The failure mode worth naming is the org chart document: a knowledge base structured as Finance, Operations, Facilities, IT, because that is how the company is arranged. A new employee wanting to book a projector has no idea which department owns projectors. Structure by the question the reader has, not by who answers it.

Space, alignment, and the parts of design writers control

You may never choose a typeface. You will constantly choose line length, spacing, alignment and emphasis, and those matter more. Text set across too wide a measure is tiring because the eye loses the line on the return sweep; a comfortable range for body text is roughly 50 to 75 characters per line. Left-aligned text with a ragged right edge is easier to scan than justified text, which opens uneven rivers of space between words. Related items should be visibly closer to each other than to unrelated ones, and consistent alignment down a left edge creates an invisible line that the eye follows for free.

Emphasis is a budget, not a decoration. Bold works because most of the page is not bold. A paragraph with six bolded phrases has spent the budget and highlighted nothing. Reserve emphasis for terms the scanning reader is hunting, and never use it to signal that a sentence is important, since every sentence you kept should be.

Key idea: White space, alignment, and restraint in emphasis are not aesthetics. They are how a page tells a reader what belongs with what.

Common misconceptions

• Design is what happens after the writing. In the Nebraska study, restructuring alone improved measured usability by 47 percent without changing a single fact.
• The F-pattern is how people read. It is how people read a page that gives them no structure. Good headings and lists change the pattern.
• Bullets always improve clarity. Bullets flatten relationships. Use them for parallel items and prose for reasoning.
• Headings are for navigation only. Descriptive headings carry the argument, and a reader who reads only your headings should still get the finding.
• A bigger font makes a heading. Heading levels are structure. Skipping a level to get a size breaks tables of contents and screen reader navigation.
• More emphasis makes important things stand out. Emphasis is relative. Bolding six phrases in a paragraph bolds nothing.

Where this leaves us

• Restructuring alone measurably improves usability; combined with concision and neutral wording it more than doubled it in the Nielsen and Morkes study.
• Readers scan, so the first words of headings and lines are the most valuable space on the page.
• Descriptive headings state findings; label headings name slots. Write the descriptive kind and you will catch pointless sections.
• One idea per paragraph, announced first, with paragraphs short enough to judge from the opening line.
• Two-dimensional content goes in a table, which also exposes facts you never supplied.
• Choose an organizing pattern from the reader's task; never structure a document to mirror an org chart.

Sources

1. Morkes, J., and Nielsen, J. (1997). Concise, scannable, and objective: How to write for the web. Nielsen Norman Group. nngroup.com
2. Nielsen, J. (2006). F-shaped pattern for reading web content. Nielsen Norman Group. nngroup.com
3. PlainLanguage.gov. Design for reading. Federal plain language guidelines. plainlanguage.gov
4. Digital.gov. Design for understanding. U.S. General Services Administration. digital.gov

Ninety-five point nine percent

Every year since 2019 the WebAIM group at Utah State University has run automated accessibility tests across the home pages of the top one million websites. In the 2026 report, 95.9 percent of those home pages had detectable failures against the Web Content Accessibility Guidelines, up from 94.8 percent the year before, reversing six years of small improvements. The two most common failures were low contrast text and images with no alternative text. Both are authoring failures, not engineering failures. Somebody chose a grey, and somebody left a box empty.

That is the useful thing about the number. Automated tools catch only a subset of accessibility problems, so the true rate is higher, and the failures they do catch are overwhelmingly the ones a writer or content author creates. This lesson is about the part of accessibility that belongs to you, whether or not anyone on your team has the word accessibility in their job title.

Four principles, one acronym worth knowing

The Web Content Accessibility Guidelines, maintained by the World Wide Web Consortium and now at version 2.2, organize everything under four principles. Content must be perceivable (a person can sense it, through sight, hearing, or touch), operable (a person can navigate and use it, including by keyboard alone), understandable (the language and behaviour are predictable), and robust (it works with assistive technology). Each principle contains testable success criteria at three levels, A, AA, and AAA. In practice, AA is the target: it is the level referenced by the United States Section 508 requirements for federal information technology and by procurement rules in many other jurisdictions.

You do not need to memorize criterion numbers. You need to know which failures come from writing and content decisions, and there are about six of them. They follow.

Alternative text, decided by function

Alternative text is the text a screen reader announces in place of an image. The mistake almost everyone makes is to describe the picture. The correct question is what the image is doing on this page.

The image	Its job	Alt text
A photo of a smiling team beside an article about a product launch	Decorative	Empty. Mark it decorative so the screen reader skips it.
A screenshot of the Settings pane with the Sync toggle circled	Shows where a control is	Settings pane with the Sync toggle switched on
A logo that is also the link to the home page	Functional: it is a link	Atlas Open Academy home
A warning triangle beside a paragraph	Conveys the meaning "warning"	Warning
A line chart of monthly failures	Carries data	Short alt naming the chart, plus the finding and the data in the text or a table

The chart row is the one people get wrong most. "Chart showing monthly failure rates" tells a blind reader nothing they could not have guessed from the caption. If a chart is worth including, its finding is worth stating in words: "Failures fell from 42 in January to 9 in June, with a spike of 61 in March after the supplier change." Write that sentence anyway. Sighted readers skim charts badly too, and a stated finding helps everybody.

Three habits to drop: do not begin with "image of" or "picture of", since the screen reader already announces that it is an image; do not stuff keywords in; and never leave the field with the file name in it, because "IMG_20240412_final2.png" read aloud is worse than silence.

Why this matters: Alt text is not a description of pixels. It is a replacement for the image's job on the page.

Headings are structure, not font size

A screen reader user typically navigates a long document by jumping from heading to heading, exactly the way a sighted reader scans. That works only if the headings are real headings, applied with the document's heading styles or HTML heading elements. A line of body text set to 16 point bold looks like a heading and is invisible to that navigation. The document becomes one undifferentiated block, and the only way through it is start to finish.

The fix takes seconds and is the single highest-value accessibility habit a writer has: use the styles. In a word processor that means applying Heading 1, Heading 2, Heading 3 rather than changing size and weight by hand. It also means not skipping levels, since the hierarchy is what tells a listener whether they have moved to a sibling section or into a subsection.

Colour, contrast, and what colour must never do alone

Two separate requirements get confused. The first is contrast: normal-size text must have a contrast ratio of at least 4.5 to 1 against its background at level AA, and large text (about 18 point, or 14 point bold) at least 3 to 1. Interface components and meaningful graphics need at least 3 to 1. Light grey text on white is the most common failure on the web, and it usually arrives from a designer who tested it on a bright screen in a dark room.

The second is that colour must never be the only carrier of meaning. A table where overdue rows are red and current rows are green fails for a reader who is colour blind, for a reader using a screen reader, and for anyone who prints it in black and white. The fix is not to remove the colour. It is to add a second signal: the word Overdue in the row, or a symbol, or a separate column. Colour then becomes redundant reinforcement, which is what colour is good at.

In short: Keep the colour. Add a signal that survives without it.

Links that mean something on their own

Screen reader users can pull up a list of every link in a document and move through it. In that list, all context is gone. A page whose links read "click here", "click here", "read more", "here" is a page whose link list is useless. Write the link text as the destination or the action: "Download the 2026 accessibility report", "Section 508 requirements for documents". The same practice helps sighted scanners, who read link text as a heading of sorts, and it helps anyone using voice control, who has to say the link's name aloud to click it.

Avoid the raw URL as link text as well. A screen reader may read a long address character by character. If you must print a URL because the document will be read on paper, print it in the text and link a human phrase.

Tables, and the difference between data and layout

A data table needs marked header cells so that a screen reader can announce, when the user lands on a cell deep in the grid, which column and row it belongs to. Without headers a listener hears "No" with no way to know that it means the audit log is absent from the standard plan. Two more rules: give the table a caption or a preceding sentence that says what it contains, and avoid merged and split cells in anything a reader must navigate, because they scramble the coordinate system.

Using a table purely to position things on a page is a separate sin, and it is mostly a legacy habit from older word processing and email. A layout table is announced as a table, so the listener is told there is a five-column grid when there is only a paragraph beside a picture.

The PDF problem

PDF is where accessible documents go to die, and it is worth understanding why. A PDF is a description of marks on a page. Unless the file carries a tag tree describing which marks are headings, paragraphs, lists, table cells and figures, assistive technology has to guess, and its guesses about reading order in a multi-column layout are usually wrong. Worse, a PDF made by scanning a printed page contains no text at all, only an image of text, and is completely unreadable to a screen reader until optical character recognition is run over it.

The practical route is to build accessibility upstream. Write in a tool that supports real heading styles, alt text and table headers; set the document language; then export to tagged PDF and check the result rather than trying to repair an untagged file afterwards. And ask whether the document needs to be a PDF at all. A web page is accessible by default in ways a PDF has to be made accessible on purpose.

Plain language is an accessibility feature

The understandable principle covers more than screen readers. Readers with cognitive and learning disabilities, readers with limited literacy, readers under stress and readers working in a second language are all served by the same things: short sentences, common words, one idea per paragraph, defined terms, consistent naming, and predictable structure. That list is the previous two lessons. Accessibility and plain language are not neighbouring concerns that happen to overlap. They are largely the same concern, approached from two directions.

Worth holding on to: Nearly everything that makes a document accessible also makes it faster for everyone else. The curb cut was built for wheelchairs and is used by every parent with a pushchair.

Common misconceptions

• Accessibility is the developer's job. The two most common detected failures, low contrast and missing alt text, are authoring decisions.
• Alt text should describe the picture. It should replace the picture's function. A decorative photo takes empty alt text; a chart needs its finding stated in the prose.
• Bold, large text is a heading. Only a real heading style is a heading. Visual weight is invisible to heading navigation.
• Avoid colour to be accessible. Use colour freely, but never as the only signal. Add a word or symbol that carries the same meaning.
• An automated checker proves a document is accessible. Automated tools catch a subset. The WebAIM figures are detected failures, which is a floor, not a ceiling.
• Accessibility is a small minority concern. Contrast helps anyone on a phone in sunlight; captions help anyone in a noisy room; structure helps every scanning reader.

What to remember

• WCAG organizes accessibility under four principles: perceivable, operable, understandable, robust. Level AA is the practical target and the one referenced by Section 508.
• Write alt text from the image's job: empty for decorative, functional for links, and the finding in prose for charts.
• Apply real heading styles and never skip levels, because heading navigation is how many readers move through long documents.
• Meet the contrast minimums, and never let colour be the only carrier of meaning.
• Link text must make sense in a list stripped of context, so avoid "click here" and bare URLs.
• Mark header cells in data tables, avoid layout tables, and prefer generating a tagged PDF over repairing an untagged one.

Sources

1. WebAIM. (2026). The WebAIM Million: An annual accessibility analysis of the top 1,000,000 home pages. Utah State University. webaim.org
2. World Wide Web Consortium. Web Content Accessibility Guidelines (WCAG) 2.2. w3.org
3. W3C Web Accessibility Initiative. Images tutorial: an alt decision tree. w3.org/WAI
4. U.S. General Services Administration. Create accessible documents. Section508.gov. section508.gov
5. Youngblood, S. A. (2013). Communicating web accessibility to the novice developer. Journal of Business and Technical Communication, 27(2), 209-232. doi.org/10.1177/1050651912458924

Take two tablets by mouth twice daily

In 2006 a team led by Terry Davis published a study in the Annals of Internal Medicine of 395 adults waiting to see their doctors at primary care clinics in Shreveport, Jackson and Chicago. Patients were shown labels from common prescription medicines and asked to explain the instructions, and then to demonstrate them with pills. One label read: take two tablets by mouth twice daily. Among patients reading at or below a sixth-grade level, 70.7 percent correctly stated the instruction back. Only 34.7 percent could then show the number of pills to take in a day.

Read those two numbers together, because the gap between them is the whole subject of this lesson. Comprehension of the words is not the same as ability to act. More than half of the people who repeated the sentence correctly could not carry it out. The label was not ungrammatical, was not misspelled, and would have passed any editing check you can name. It failed the only test that mattered, and nothing in the writing itself would have told you so. Instructions cannot be evaluated by reading them. They can only be evaluated by watching someone use them.

Your reader is not reading, they are doing

When John Carroll and his colleagues at IBM watched people learn word processing systems in the 1980s, they found behaviour that manual writers found infuriating and that is completely normal. Learners did not read the manual through. They skipped ahead to the task they wanted, invented steps, acted before reading, made errors, and then hunted for recovery information that was not there. Carroll's response, which became the minimalist approach to documentation, was to stop treating this as bad behaviour and design for it: organize around real tasks, cut the introductory material, get the reader acting immediately, and make error recovery a first-class part of the document rather than an appendix.

Research on how people process procedural instructions has since reinforced the picture. A reader in the middle of a task is holding equipment, watching a screen, tracking where they are in the sequence, and has very little attention left for prose. Every sentence that does not directly move the task forward is competing with the task for the same scarce resource.

The point: Instructions are read in fragments by someone whose hands are busy. Design for interruption, error, and re-entry, not for a patient reader at a desk.

The parts of a procedure

A complete procedure has a predictable skeleton. Leaving a part out is the most common structural failure, and each omission produces a characteristic kind of stuck reader.

Part	What it does	What happens if you omit it
Task title, as a verb phrase	Lets a reader find it and confirm it is the right procedure	Readers follow the wrong procedure to step four before noticing
When to use this, and when not to	Sets scope	The procedure gets applied to a case it was never meant for
Prerequisites	Access, tools, parts, permissions, states	Reader gets to step six and discovers they lack an admin role
Warnings and cautions, before the relevant step	Prevents harm and damage	The reader learns about the hazard after performing it
Numbered steps	Sequence the actions	Order becomes a guess
Results after key steps	Confirms the reader is still on track	Silent divergence; the reader continues down a broken path
Verification at the end	Tells the reader they are done and it worked	Nobody knows whether the task succeeded
Troubleshooting	Recovery for the likely failures	The reader calls you, which is the cost you were trying to avoid

How to write a single step

Six rules cover nearly everything, and they are all testable against a draft.

1. One action per step. If a step contains "and then", split it. Readers lose their place inside compound steps.
2. Imperative mood, second person. "Select Reset password." Not "The reset password option should be selected", and not "The user can now select".
3. Location before action. "In the Actions menu, select Reset password." Putting the location first stops the reader from hunting the whole screen for a control they have already been told to click.
4. State the visible result when it is not obvious. "A temporary password appears." This is how a reader knows the step worked before committing to the next one.
5. Number only what is sequential. Numbers promise order. If three things can be done in any order, use bullets, or the reader will assume a dependency that does not exist.
6. Never bury a condition inside a step. "Select Save, unless you are using single sign-on, in which case select Apply" should be two labelled branches. A reader mid-task will read the first half and act.

Warnings that actually prevent harm

Research on warning design, summarized by Michael Wogalter and colleagues in Applied Ergonomics, converges on a structure with three components: the hazard, the consequence, and the instruction. "High voltage" is a hazard with no instruction. "Disconnect power at the breaker before removing the cover. Live terminals inside can cause fatal shock." names all three.

Placement matters as much as wording, and it is where documents most often fail. A warning belongs immediately before the step that creates the exposure, not collected on a safety page at the front that the reader skipped. The American national standard for safety signs also fixes a hierarchy of signal words that many industries follow: DANGER for a hazard that will cause death or serious injury, WARNING for one that could, CAUTION for one that could cause minor or moderate injury, and NOTICE for property damage with no injury risk. Using DANGER for a data-loss risk devalues the word for the case where someone might die.

One procedure, rewritten

Before: "Password resets are handled through the admin console. It should be noted that resetting a password will terminate all of the user's active sessions, so it is advisable to coordinate with the user beforehand. Navigate to the console and, after locating the user in question via the search function, the Reset Password option can be selected from the actions menu, which will generate a temporary password that must be communicated to the user through a secure channel; note that temporary passwords expire after 24 hours and that if the user has multi-factor authentication enabled you will also need to clear the enrolled device, which is done from the same menu."

After:

Reset a user's password

Use this when a user cannot sign in and has confirmed their identity to you. You need the Account Administrator role.

Caution: Resetting a password signs the user out of every device immediately. Agree a time with them first.

1. In the admin console, search for the user by email address.
2. Open the user's record and select Actions, then Reset password. A temporary password appears.
3. Send the temporary password to the user by a channel other than email, such as a phone call. It expires after 24 hours.
4. If the user has multi-factor authentication turned on, select Actions, then Clear enrolled device. Otherwise skip this step.

Check it worked: Ask the user to sign in with the temporary password. They should be prompted to choose a new one.

If the user does not receive the prompt: confirm the temporary password has not expired, then repeat from step 2.

Count what changed. The warning moved from the middle of a sentence to a labelled block above the steps. A hidden prerequisite, the administrator role, became explicit. A conditional buried in a subordinate clause became its own step with a stated alternative. Two results were added so the reader can tell they are on track. And a verification step now exists, which the original never had, meaning nobody using the old version could tell whether they had finished.

Remember: Most instruction defects are not sentence defects. They are missing parts: no prerequisite, no result, no verification, no recovery.

The test that decides everything

Here is a protocol that costs twenty minutes and will change how you write. Find one person who plausibly resembles your reader and has not seen the draft. Give them the instructions and the real task. Then sit behind them, say nothing, and write down three things: every place they hesitate for more than a couple of seconds, every place they do something other than what you intended, and every question they ask out loud. Do not answer the questions. Say you will answer afterwards.

Two rules make the results usable. First, when a tester fails, the document failed, not the tester. The instinct to say "well, they should have known that" is the curse of knowledge speaking, and every time you give in to it you protect a defect. Second, do not fix the wording at the point of failure until you know why they failed there, because a hesitation at step four is very often caused by a missing prerequisite at the top. Five testers will surface most of the serious problems in a procedure; even one is transformative compared with none.

Common misconceptions

• If the instruction is grammatically clear, it works. Two thirds of the patients in the Davis study who could repeat the label could not act on it.
• Readers who skip ahead are careless. Skipping ahead is normal behaviour that documentation should be designed around, which is Carroll's central finding.
• Safety information belongs at the front. It belongs immediately before the step that creates the hazard. A front-loaded safety page is a page readers skip.
• More warnings mean more safety. Overusing DANGER for minor risks trains readers to ignore the word when it matters.
• Numbering everything makes a procedure clearer. Numbers promise a required order. Use bullets when order does not matter.
• Testing needs a lab and a budget. One person, a real task, and a writer who keeps quiet will find most of the serious defects.

Pulling it together

• Stating an instruction correctly and being able to perform it are different abilities, and only the second one counts.
• Readers act while reading, skip ahead, and make errors. Design for recovery instead of assuming compliance.
• A procedure needs a task title, scope, prerequisites, placed warnings, numbered steps, results, verification, and troubleshooting. Missing parts cause predictable failures.
• Steps take one action each, in the imperative, with location before action and the visible result stated.
• A usable warning names the hazard, the consequence, and the instruction, and sits immediately before the risky step.
• A twenty-minute test with one real user outranks any amount of rereading, and every failure is a document defect.

Sources

1. Davis, T. C., Wolf, M. S., Bass, P. F., et al. (2006). Literacy and misunderstanding prescription drug labels. Annals of Internal Medicine, 145(12), 887-894. doi.org/10.7326/0003-4819-145-12-200612190-00144
2. Ganier, F. (2004). Factors affecting the processing of procedural instructions: Implications for document design. IEEE Transactions on Professional Communication, 47(1), 15-26. doi.org/10.1109/TPC.2004.824289
3. Wogalter, M. S., Conzola, V. C., and Smith-Jackson, T. L. (2002). Research-based guidelines for warning design and evaluation. Applied Ergonomics, 33(3), 219-230. doi.org/10.1016/S0003-6870(02)00009-1
4. Microsoft. Procedures and instructions. Microsoft Writing Style Guide. learn.microsoft.com

What developers actually complain about

In 2015 Gias Uddin and Martin Robillard published a study in IEEE Software with the blunt title "How API Documentation Fails." Rather than asserting what good documentation looks like, they collected the problems developers reported in practice and sorted them. The list divides cleanly in two. There are content problems: the documentation is incomplete, ambiguous, or simply wrong. And there are presentation problems: it is bloated, fragmented across too many places, tangled with unrelated material, or inconsistent with itself.

Notice which of those a careful writer would catch by rereading. Almost none. Ambiguity is invisible to the person who knows what was meant. Fragmentation only appears when someone tries to complete a task and has to open five pages. Incorrectness appears when the code changes and the prose does not. Later work by Meng, Steinhardt and Schubert, surveying and interviewing developers about what they want, found the same demand appearing over and over: complete, runnable examples, not descriptions of what the code would do. Documentation for software is judged in use, like a procedure, and almost never by how it reads.

Four kinds of documentation, and the harm in mixing them

The most useful organizing idea in this field is Daniele Procida's observation that software documentation serves four distinct needs, and that most bad documentation is a page trying to serve two at once. The framework is called Diataxis.

Kind	The reader is	It must	Failure when mixed
Tutorial	Learning, with no goal of their own yet	Guarantee a successful first experience on a fixed path	Adding options and caveats makes the beginner choose, and they get lost
How-to guide	Working, with a specific goal	Get a competent user to a defined result	Adding teaching material forces the working reader through explanation they do not want
Reference	Working, needing a fact	Be complete, accurate, consistent, and boring	Adding narrative makes facts unfindable and lets gaps hide
Explanation	Studying, wanting to understand why	Give context, alternatives, and design reasoning	Adding steps makes it look actionable when it is not

Take one concrete case. A tutorial says: run this exact command, then this one, and you will see a running server. It deliberately does not mention that there are four ways to configure the port, because a beginner offered four ways will stop and try to decide, and deciding is precisely what they cannot do yet. The reference page lists all four with their defaults and constraints, because a reference that leaves out an option is broken. Both pages are correct, and neither could be the other.

Key idea: Ask what state the reader is in, not what the page is about. Learning and working are different states, and they need different pages.

The README is a decision document

The first page of a project is not documentation about the project; it is the document on which someone decides whether to spend their afternoon on it. In the first screen it should answer: what is this, what problem does it solve, and who is it for. Then, quickly: does it run on my platform and version, how do I install it, and what is the smallest example that does something real. Then, findable but lower: where the full reference lives, what the licence is, how to report a problem, and whether the project is maintained.

The most common README defect is opening with architecture. A paragraph about the modular plugin pipeline answers a question nobody has yet asked. The second most common is an installation section that assumes a state the reader is not in, and the third is an example that has never been run in the state the README describes and therefore does not work.

Anatomy of a reference entry

Here is a typical entry as it often appears, and then as it should appear.

Before: "GET /v1/invoices/{invoice_id} - Gets an invoice. Parameters: invoice_id (required), expand (optional). Returns the invoice object."

After:

GET /v1/invoices/{invoice_id}

Returns a single invoice, including its line items. Use this when you have an invoice identifier and need its current state. To list invoices for a customer, use GET /v1/invoices with a customer filter instead.

Authentication: a secret API key with the invoices.read scope. Keys with only the payments scope receive 403.

Parameter	In	Type	Required	Notes
invoice_id	Path	String	Yes	Begins with inv_. Identifiers are case sensitive.
expand	Query	Array of strings	No	Accepts customer and payment_method. Maximum of two values. Unknown values return 400.

Example request: GET /v1/invoices/inv_8f21b0 with the header Authorization: Bearer YOUR_SECRET_KEY

Example response: a 200 response containing id, status (one of draft, open, paid, void), amount_due in the smallest currency unit, currency as a three-letter ISO code, created as a Unix timestamp in seconds, and lines as an array.

Error	Means	What to do
400	An expand value is not recognized	Check spelling against the allowed values above
403	The key lacks the invoices.read scope	Use a key with that scope; scopes cannot be added to an existing key
404	No invoice with that identifier in this account	Confirm you are using the right environment; test and live identifiers are separate
429	Rate limit exceeded, 100 requests per second per key	Retry after the interval in the Retry-After header, with exponential backoff

Everything added here answers a question that would otherwise become a support ticket. The prefix of the identifier, the case sensitivity, the separation of test and live identifiers, the exact allowed values of expand, the units of the amount, the meaning of each error and what to do about it. The original entry was not wrong. It was merely useless, which is a distinction developers make constantly and writers often miss.

What matters here: A reference entry is complete when a competent developer can succeed from that page alone, without guessing and without asking you.

Error messages are documentation with a smaller budget

The error message is the documentation that reaches the most readers at the worst moment, and it is usually written by whoever was closest to the keyboard. A usable error message has three parts, exactly like a warning: what happened, why, and what to do next.

"An error occurred" has none of them. "Invalid input" has one. "Could not create the invoice: currency must be a three-letter ISO 4217 code, and you sent 'dollars'. Use USD." has all three, names the offending value, and states the fix. Two further rules: do not blame the user, and never expose an internal identifier as the entire message, because "Error 0x8007000E" sends the reader to a search engine rather than to a solution. If the message must carry a code for support, put the code after the human sentence, not instead of it.

Keeping documentation true

The hardest problem in this genre is not writing but decay. Code changes hourly; prose does not. Three practices address it, and mature teams use all three.

Generate what can be generated. Machine-readable API descriptions, most commonly written to the OpenAPI Specification, let the parameter tables, types, and status codes come from a single source that also drives client libraries and tests. What a generated reference cannot supply is the purpose sentence, the cross-reference to the right alternative endpoint, or the note about test and live identifiers. Generate the skeleton, write the judgment.

Keep the docs in the repository with the code. The docs-as-code approach stores documentation as plain text under version control, reviewed in the same pull request as the change that caused it. This is the single most effective anti-staleness measure available, because it makes the documentation update part of the definition of done rather than a separate task that gets deferred forever.

Test the examples. An example in documentation is a claim about behaviour, and claims can be executed. Teams that run their documentation examples in continuous integration find breakages the day they occur rather than when a customer reports that the quickstart no longer works.

Bottom line: The question is not whether your documentation is good today. It is whether the process makes it wrong tomorrow.

Common misconceptions

• Good documentation is one comprehensive page. One page cannot serve a learner and a working developer. The four kinds have incompatible requirements.
• A tutorial should mention the alternatives. Options are what a beginner cannot yet evaluate. Put them in reference.
• Auto-generated reference is enough. Generation gives you names and types. It cannot tell a reader which endpoint to use instead, or why an identifier fails across environments.
• Error messages are engineering, not writing. They are the highest-traffic documentation in most products.
• Self-documenting code removes the need for documentation. Code can show what it does. It cannot state what it guarantees, what it costs, or what it will keep doing next release.
• Documentation goes stale because writers are careless. It goes stale because the process lets a code change ship without the doc change.

The takeaway

• Developers report failures of content (incomplete, ambiguous, incorrect) and of presentation (bloated, fragmented, inconsistent), and rereading catches almost none of them.
• Diataxis separates tutorial, how-to, reference, and explanation by the reader's state; mixing two on one page harms both.
• A README is a decision document, so it answers what this is and whether it runs before it discusses architecture.
• A reference entry is complete when a developer can succeed from that page alone: purpose, auth, parameters with constraints, a worked example, and every error with a remedy.
• An error message needs what happened, why, and what to do, with the offending value named.
• Fight staleness with generation for the mechanical parts, docs in version control reviewed with the code, and examples that run in continuous integration.

Sources

1. Uddin, G., and Robillard, M. P. (2015). How API documentation fails. IEEE Software, 32(4), 68-75. doi.org/10.1109/MS.2014.80
2. Meng, M., Steinhardt, S., and Schubert, A. (2018). Application programming interface documentation: What do software developers want? Journal of Technical Writing and Communication, 48(3), 295-330. doi.org/10.1177/0047281617721853
3. Procida, D. Diataxis: A systematic framework for technical documentation authoring. diataxis.fr
4. OpenAPI Initiative. OpenAPI Specification. spec.openapis.org
5. Write the Docs. Docs as code. writethedocs.org

A slide that said the opposite of what it knew

Columbia launched on 16 January 2003. About 82 seconds in, a piece of insulating foam broke off the external tank and struck the orbiter's left wing. A team of NASA and contractor engineers was assembled to work out what the strike had done. They had a model called Crater, built years earlier to predict how deep a projectile would dig into the thermal protection tiles. Eight days into the flight they presented their assessment to the Mission Evaluation Room, and they presented it as PowerPoint slides.

One slide carried a headline saying that a review of test data indicated conservatism for tile penetration. Read the headline alone and you would conclude the wing was probably fine. Four levels down the bullet hierarchy, in the smallest type on the slide, sat the fact that the test data used to calibrate Crater came from projectiles far smaller than the foam that had actually hit the wing. The model was being run well outside the range it had been validated against, and that fact had been demoted to a sub-sub-bullet underneath a reassuring title.

Columbia broke up over Texas on 1 February 2003. The Columbia Accident Investigation Board, reporting that August, made an argument that belongs in a writing course rather than an engineering one: NASA had got into the habit of substituting briefing slides for technical papers, and the substitution had a cost. A slide lets you assert a conclusion in a headline and never write the sentence that joins the evidence to it. A paragraph does not let you off. To write "the test data supports this conclusion because" you have to finish the sentence, and finishing it is often where you discover that you cannot.

Key idea: The form of a document is not neutral. Some forms make it possible to skip the reasoning; a report is the form that makes you show it.

Five reports, one job

Report is a word that covers several genres with different obligations. Naming yours before you draft saves you from writing a hybrid that serves nobody.

Genre	The reader's question	What it must contain
Incident report	What happened, and will it happen again?	A timeline, the contributing causes, the corrective actions with owners and dates
Feasibility study	Can we do this, and at what cost?	Options, criteria, an assessment against each criterion, a cost and risk picture
Recommendation report	Which option should we choose?	One recommendation stated first, the alternatives considered, the basis for rejecting them
Progress report	Are we on track, and do you need anything from me?	Status against plan, what changed, blockers with a specific ask
White paper	How should I think about this problem?	A problem framed independently of any one vendor, approaches, evidence, limits

Notice that every one of these is a decision document, even the progress report, whose decision is usually "do I need to intervene this week." Nothing in the list is a record of your effort. The most common failure in workplace reporting is a document organized around what the author did, in the order the author did it, when the reader needs it organized around what the reader must now decide.

The executive summary is a whole document

Here is the rule that separates people who write reports from people who write long documents with a heading at the top that says Executive Summary: the summary must work when detached. Assume it will be pasted into an email and forwarded to somebody who will never open the attachment, because that is what happens.

Which means an executive summary is not an introduction. An introduction sets up. A summary delivers. Compare these two openings for a report on a support desk that has slipped.

Before, an introduction wearing a summary's name:

"This report presents the findings of a review of the Customer Support function conducted between March and June. The review was commissioned by the Operations Director following concerns raised at the February management meeting. Section 2 describes the methodology, Section 3 presents the data collected, Section 4 offers analysis, and Section 5 sets out recommendations for consideration by the leadership team."

After, a summary that survives detachment:

"Support cannot absorb its current ticket volume, and the gap is widening. Median time to first response rose from 4 hours in January to 31 hours in June, while ticket volume rose 60 percent and staffing did not change. We recommend two actions before 1 September: move password resets to self-service, which would remove 38 percent of tickets at an estimated one-off cost of 12 engineering days, and hire two agents. Doing only the first returns median response time to roughly 9 hours on our modelling, which is above the 4 hour target but inside the service agreement. Doing neither means the agreement is breached in the fourth quarter."

The second version has a number in nearly every sentence, names the decision, prices it, and says what happens if the reader does nothing. It also does something the first version cannot: it lets a reader disagree. A reader who thinks the 38 percent figure is wrong now knows exactly which claim to attack. Vagueness is not neutral; it protects the writer from being checked.

The upshot: If your summary would still be true after the recommendation changed, it is not a summary.

Findings, conclusions, and recommendations are three different things

Most weak reports blur these three into one soup called "analysis". Keep them apart and the report almost writes itself, because each has its own grammar.

	What it is	How to test it	Example
Finding	Something you observed or measured	Could a second person, given the same access, produce the same statement?	Median time to first response rose from 4 hours in January to 31 hours in June.
Conclusion	What the findings mean together	Does every finding it rests on appear in the report?	The team cannot absorb current volume at current staffing.
Recommendation	An action, with an owner and a date	Could somebody start work on Monday from this sentence alone?	Move password resets to self-service by 1 September. Owner: platform team.

Two failure modes follow from mixing them. The first is the finding dressed as a conclusion: "response times are unacceptable" sounds like a measurement and is actually a judgment, and the reader cannot tell which number produced it. The second is the recommendation with nobody in it: "consideration should be given to increasing self-service capability" has no actor, no date, and no cost, and will be nodded at and forgotten. Notice it is also passive voice with the actor deleted, which is exactly the plain language failure from Module 1 arriving in a new costume.

The order of a decision report

Academic writing built you a habit: method, then results, then discussion, then conclusion. That order exists so a reviewer can check your work before learning what you claim. A workplace reader has the opposite need, so the order inverts.

1. Recommendation or bottom line, in the first paragraph.
2. The basis: the two or three findings the recommendation rests on.
3. The alternatives you considered and why you rejected them. Skipping this is what makes a report look like advocacy.
4. Method, in enough detail that a sceptic could repeat it.
5. Detail, tables, and raw data, in appendices.

The U.S. Government Accountability Office publishes hundreds of reports a year in a fixed public shape: a one-page highlights sheet saying what GAO found, why GAO did the study, and what GAO recommends, sitting in front of a report that can run to a hundred pages. It is a useful model precisely because the audience is a legislator with fifteen minutes. The highlights page is not a courtesy. It is the part most readers will read.

Jakob Nielsen borrowed the newsroom's name for this shape, the inverted pyramid: most important information first, then supporting detail in descending order, so that a reader who stops at any point has taken away the most valuable thing available up to there. It is a good test to apply to your own draft. Cut it after paragraph two. Is what remains still useful and still true?

What matters here: Put the conclusion where the reader is, not where your reasoning ended.

One recommendation, rewritten

Before: "It is recommended that the organization explore opportunities to enhance the efficiency of the support intake process, potentially including the leveraging of automation solutions where appropriate, in order to better align capacity with demand going forward."

After: "Move password resets to self-service by 1 September. The platform team owns this. It costs about 12 engineering days and removes 38 percent of tickets, which brings median first response from 31 hours to roughly 9."

Forty-two words become thirty-eight, so this is not about length. Look at what changed. An actor appeared. A deadline appeared. A cost appeared. A predicted effect appeared, with a number that can be checked against reality in October. "Explore opportunities to enhance" became a verb that names a thing somebody does. And the hedges that were doing no work went: potentially, where appropriate, going forward. The one hedge that mattered, the word "roughly" in front of 9 hours, stayed, because the modelling really is approximate and saying so is honest rather than weak.

White papers, and where the genre goes wrong

The term comes from government. A white paper was a policy document setting out a position for discussion, distinct from the internal green paper that floated options. Technology marketing borrowed the name, and the genre now covers everything from a serious analysis of a standards problem to a brochure with footnotes.

An honest white paper has a recognizable skeleton: a problem stated in the reader's terms and framed so that more than one solution could address it, an account of how the problem is currently handled and what that costs, a proposed approach, evidence, and an explicit statement of where the approach does not apply. That last section is the tell. A document with no limitations section is a sales document, whatever the file is called.

The dishonest version does its work at the framing stage rather than in the claims, which is why fact-checking a bad white paper often turns up nothing false. Watch for the problem statement engineered to have exactly one exit: describe the difficulty as "the inability to unify observability data in a single pane of glass" and you have not described a problem, you have described the absence of the sponsor's product. Watch also for the case study with no denominator, where three named customers succeeded and you are not told how many tried, and for the comparison table where the competitor's row was filled in by the sponsor.

If you are writing one for an employer, two practices keep it defensible. Disclose the sponsorship in the document itself, on the first page rather than the last. And write the problem statement so that a competitor's product would also be a legitimate answer to it. If you cannot, you are not writing about a problem.

Bottom line: A white paper earns trust by being useful to a reader who does not buy anything, and it can only do that if the problem was real before the product existed.

Common misconceptions

• The executive summary is written first. It is written last, from the finished findings, then moved to the front. Written first, it becomes a plan you then defend rather than a conclusion you reached.
• A summary should be neutral and leave the decision open. A summary that hides the recommendation forces every reader to redo the work you were paid to do.
• Recommendations should be tactful, so soften them. Softening removes the actor, the date, and the cost, which is exactly the information that makes a recommendation actionable. Be direct about the action and careful about the tone.
• Long reports signal thoroughness. Length signals that you did not decide what mattered. Appendices exist so the body can stay short without discarding evidence.
• Slides are a faster version of a report. They are a different genre with different failure modes. A slide can carry an assertion without its reasoning, which is the failure the Columbia board described.
• A white paper is objective because it has citations. Framing does the persuading. Check whether the problem statement admits a solution other than the sponsor's.

Summing up

• Reports are decision documents, so organize them around the decision rather than around what you did.
• The executive summary must survive being detached and forwarded on its own, which means it carries the recommendation, the numbers, and the consequence of inaction.
• Findings are observed, conclusions are inferred, recommendations are actions with an owner and a date. Keep the three in separate sentences.
• Invert the academic order: bottom line, basis, alternatives rejected, method, appendices.
• A vague recommendation is not tactful, it is unusable. Name the actor, the date, the cost, and the expected effect.
• Judge a white paper by its problem statement and its limitations section, not by its footnotes.

Sources

1. Columbia Accident Investigation Board. (2003). Columbia Accident Investigation Board Report, Volume 1. National Aeronautics and Space Administration.
2. Tufte, E. R. (2006). The Cognitive Style of PowerPoint: Pitching Out Corrupts Within (2nd ed.). Graphics Press.
3. U.S. Government Accountability Office. Reports and testimonies. gao.gov
4. Nielsen, J. (1996). Inverted pyramids in cyberspace. Nielsen Norman Group. nngroup.com
5. PlainLanguage.gov. Federal plain language guidelines. plainlanguage.gov

Three headings, or nobody reads it

A research proposal to the U.S. National Science Foundation opens with a project summary of no more than one page. That page must contain three separately labeled sections: an overview, a statement on the intellectual merit of the proposed activity, and a statement on its broader impacts. A summary that discusses intellectual merit beautifully inside a flowing paragraph, without the label, can be returned without review. Years of work, a team of collaborators, and a genuinely good idea, stopped at the door by a missing heading.

This feels unfair the first time it happens to you, and it is worth understanding why the rule exists rather than resenting it. NSF sends proposals to volunteer reviewers who read many of them. A fixed structure means every reviewer finds the same thing in the same place, and a program officer can check compliance in seconds rather than reading for it. The structure is not decoration on the argument. It is the condition under which the argument gets read at all.

Every proposal you will ever write is governed by some version of this. Somebody wrote the question. Your job is to answer that question, in their order, using their words for things, inside their limits. A proposal is the one genre where the outline is not yours.

Why this matters: In every other genre in this course you decide the structure from the reader's task. In a proposal, the reader has already published the structure, and deviating from it costs points before anyone judges your idea.

Solicited, unsolicited, and the difference in burden

A solicited proposal responds to a published request. In U.S. federal contracting these arrive as an RFP, a request for proposals, sometimes preceded by an RFI, a request for information, that the buyer uses to learn what the market can do, and distinct from an RFQ, a request for quotations, which is mostly about price. Grants come through similar machinery: a funding opportunity announcement published on a portal, with a deadline measured to the minute.

An unsolicited proposal arrives uninvited, and it carries an extra burden the solicited one does not: before you can propose anything, you have to convince the reader that a problem exists and that it is worth money. Most unsolicited proposals fail there, in the first page, because the writer was excited about a solution and assumed the problem was obvious. If you are writing one, spend the first section proving the cost of the current situation in the reader's own numbers, and do not mention what you are selling until you have.

Read the evaluation criteria first, and turn them into a matrix

Federal solicitations issued under the Uniform Contract Format have a structure worth knowing even if you never bid on one, because it makes the logic visible. Section L tells you how to prepare and submit your proposal: volumes, page limits, fonts, file formats, what goes where. Section M tells you the factors on which the award will be decided, and often their relative importance.

Most first-time proposal writers read the statement of work, get interested, and start drafting. That is backwards. Read Section M first, because it is the scoring rubric. Then read Section L, because it is the set of rules under which you can be disqualified without being scored at all. Only then read the work itself.

Then build a compliance matrix. It is an unglamorous table and it wins more work than good prose does.

Requirement, in their words	Where in the solicitation	Our response, page	Evidence offered
Demonstrated experience migrating databases larger than 5 TB	M.2(a)	Vol I, p. 7	Two named projects, sizes, dates, references
Named project manager with PMP certification	L.4(c)	Vol I, p. 3	Resume, certificate number
Transition plan not exceeding 10 pages	L.6	Vol II, pp. 1-9	9 pages, within limit
Cost realism narrative for each labour category	M.3	Vol III, p. 4	Rates, hours, basis of estimate

Two things happen when you build this. First, blank cells appear, and each blank cell is a requirement you cannot meet, which is information you want on day two rather than day nineteen. Second, you stop paraphrasing. If the solicitation says "demonstrated experience", your heading says Demonstrated Experience, not Our Track Record. An evaluator scoring twenty proposals against a checklist should never have to work out that your synonym means their term. This is the one place where the Module 1 rule about naming the same thing the same way every time becomes worth money.

The core of it: The evaluation criteria are your outline. Not a source for your outline. The outline.

How proposals actually lose

Losing on the merits is the rare case. The common cases are duller.

• Non-responsive. A requirement was not addressed at all, often because it was buried in a subsection nobody re-read.
• Non-compliant. Eleven pages where ten were allowed, the wrong font size, a missing form, a file format the portal rejects. Some buyers simply do not read past the limit; some discard the submission.
• Late. Portals close on a clock, not on a person's goodwill. Uploading a large file at four minutes to deadline is a decision to gamble the whole bid on your connection.
• Unsupported. Every claim is an adjective. This is the failure that feels like writing and is actually its absence.
• Answering a different question. The reused proposal from a similar bid, with the client name changed and one paragraph left describing the wrong industry. Evaluators find this constantly.

One capability paragraph, rewritten

Before: "Our firm is a leading provider of innovative data migration solutions with extensive experience serving clients across a wide range of sectors. Our world-class team leverages industry best practices and cutting-edge methodologies to deliver high-quality outcomes on time and on budget. We pride ourselves on our commitment to customer satisfaction and our proven track record of success."

After: "We have completed nine database migrations above 5 TB since 2021. The largest, for a regional health system, moved 18 TB with 40 minutes of planned downtime and no data loss; their infrastructure director has agreed to serve as a reference and is listed in Appendix B. Two of the nine ran over schedule, both because source-system data quality was worse than the client's audit had reported, which is why our transition plan in Volume II puts a data profiling step before the cutover date is fixed."

Count the checkable claims in each. The first paragraph has none. Not one sentence in it could be false, because not one sentence says anything a competitor could not copy verbatim into their own proposal. Adjectives are free, which is exactly why evaluators discount them.

The second version does something that makes new writers nervous: it admits two projects ran late. Read it again and notice what the admission buys. It converts the surrounding numbers from marketing into testimony, and it sets up the transition plan as a considered response to a real failure rather than boilerplate. An evaluator who has run a migration knows some go long. A bidder claiming a perfect record is either lucky, new, or not telling the truth, and experienced evaluators know which is most likely.

Price, and the narrative that has to match it

In federal buying there are two broad award approaches, and knowing which one you are in changes what you write. Under a lowest price technically acceptable evaluation, proposals are rated acceptable or unacceptable against the requirements, and among the acceptable ones the cheapest wins; extra quality earns nothing. Under a best value tradeoff, the buyer may pay more for a better proposal, and must document why the premium was worth it. Writing a rich technical narrative into an LPTA competition wastes effort. Writing a thin one into a tradeoff competition loses it.

Whatever the approach, the budget and the narrative must be the same document told twice. Every line in the budget needs a sentence somewhere in the work plan that explains what that money buys, and every activity in the work plan needs a line in the budget. A number with no sentence looks like padding. A promised activity with no funding looks like a promise you have not costed. Reviewers cross-check these, and the mismatch is easy to find.

Remember: A basis of estimate is a sentence, not a number. "220 hours" is a number. "220 hours, based on 18 TB at the 1.4 TB per day throughput we measured on the health system migration, plus 40 hours of contingency" is an estimate somebody can argue with, which is what makes it credible.

Where the persuasion turns into something else

Proposal work has a practice called ghosting: writing the requirements or the discussion so that the strengths of your approach, and the weaknesses of an unnamed competitor's, are foregrounded. Emphasizing that your solution requires no proprietary hardware is legitimate ghosting if it is true and relevant. It stops being legitimate when the statement about the alternative is false, when it implies a competitor failure that did not happen, or when you help a buyer write requirements engineered to exclude everyone but you. The first is persuasion. The last is corruption of the competition, and in public procurement it can end careers.

A workable line: everything you say about your own capability must be verifiable, and everything you imply about an alternative must be something you would be willing to say with the competitor in the room.

Common misconceptions

• The best technical solution wins. The compliant, responsive, well-evidenced proposal wins. A better solution that skipped a required section is often not scored at all.
• Rewriting their terminology in your own words shows sophistication. It shows an evaluator with a checklist that your heading does not match their criterion. Use their words.
• Admitting a limitation weakens the bid. A named limitation with a mitigation is more credible than an unbroken record of success, and it gives the evaluator a reason to believe the rest.
• The budget is Finance's problem. Reviewers read the budget against the work plan and find the mismatches. An unexplained number is read as padding.
• Page limits are guidance. They are frequently enforced by discarding everything past the limit, and sometimes by discarding the submission.
• You can reuse most of a previous proposal. You can reuse evidence. Reusing structure and framing is how the wrong client name ends up on page six.

What you now know

• Proposals are the genre where the outline belongs to the reader. Read the evaluation criteria first, the submission instructions second, and the work last.
• A compliance matrix maps every requirement to a page and a piece of evidence, and its blank cells are the most useful output of the early week.
• Most proposals lose on responsiveness, compliance, timing, or unsupported claims, not on the quality of the idea.
• Replace adjectives with counts, dates, sizes, named references, and outcomes a stranger could check.
• A disclosed limitation with a mitigation strengthens a proposal, because it converts the other claims into testimony.
• Every budget line needs a sentence of work behind it and every basis of estimate needs a stated derivation.
• Ghosting is legitimate when it is true, relevant, and something you would say with the competitor present.

Sources

1. National Science Foundation. Proposal and Award Policies and Procedures Guide. nsf.gov
2. U.S. General Services Administration. Federal Acquisition Regulation, Part 15: Contracting by negotiation. acquisition.gov
3. Grants.gov. Applicant resources. U.S. Department of Health and Human Services. grants.gov
4. Freed, R. C., Freed, S., and Romano, J. (2010). Writing Winning Business Proposals (3rd ed.). McGraw-Hill.

The chart that left out the flights where nothing happened

On the evening of 27 January 1986, engineers at Morton Thiokol held a teleconference with NASA and argued that the Space Shuttle should not launch the next morning. The overnight forecast was for temperatures in the twenties Fahrenheit. The coldest launch in the programme so far had been at 53 degrees, and the rubber O-rings that sealed the joints of the solid rocket boosters stiffen as they get cold. The engineers faxed charts to support the case. The launch went ahead at about 36 degrees, and Challenger was destroyed 73 seconds later.

Edward Tufte later reconstructed what those charts showed, and the finding is one of the most useful things a technical writer can learn. The charts presented the flights that had suffered O-ring damage. They did not present the flights that had not. Plot only the damaged flights and the temperature relationship disappears into noise, because you are looking at a sample selected on the outcome. Plot all twenty-four previous flights, damaged and clean together, against launch temperature, and the pattern is visible to anyone: the cold end of the range is where the damage clusters, and the proposed launch sat far colder than any point in the data.

Nothing on those charts was false. Every plotted value was a real measurement from a real flight. The lie, if you want to call it that, was in the flights that were not on the page. This is the single most important habit this lesson can give you: ask what is missing before you check what is shown.

So what?: A chart is an argument about a population. If the selection into the chart depends on the outcome you are studying, no amount of accuracy in the plotted points can save it.

Six distortions in which every number is true

Outright fabrication is rare and easy to condemn. What follows is the everyday kind, all of which survive a fact check.

Distortion	What it does	The fix
Truncated baseline on bars	Bars starting at 94 instead of 0 turn a 2 percent difference into a bar three times taller than its neighbour	Bars encode length, so they need a zero baseline. If the interesting variation is small, use a line or a dot plot, where a non-zero range is honest, and label the range clearly
Dual vertical axes	Two series on independent scales can be made to cross, diverge, or track each other by choosing the scales; the apparent correlation is an authoring decision	Use two stacked panels sharing an x-axis, or index both series to 100 at a common starting point and say so
Area or volume for a one-dimensional quantity	Doubling a circle's radius quadruples its area, so the reader sees a fourfold difference in a twofold change	Encode magnitude with length or position. If you must use circles, scale the area, not the radius, and never use 3D shapes
Cherry-picked range	Starting the x-axis at an unusual low or high point manufactures a trend that vanishes with two more years of data	Show the longest run the data supports, or show both windows side by side and let the reader see the difference
Counts where rates belong	A map of raw counts is mostly a map of where people live; the biggest states lead every list	Divide by the population at risk and say what the denominator is. Report the count too, because a rate over a tiny denominator is unstable
Perspective and decoration	A tilted 3D pie makes the front wedge look larger than an equal wedge at the back	Remove the third dimension. For part-to-whole with more than about five categories, a sorted bar chart or a plain table beats a pie

Two of these deserve a defence of the opposite case, because the rules are often taught as absolutes and are not. A truncated axis is not automatically deceptive: a line chart of body temperature that started at zero would be unreadable, and nobody thinks a fever chart is lying. The distinction is the visual encoding. A bar says "this much" through its length, so cutting the bar cuts the meaning. A line says "it moved this way" through its slope, and the slope survives a zoomed range. And dual axes are not always wrong either, when the two quantities are genuinely different units that the reader must compare over time. They are wrong when the scales were chosen to make a story appear.

Percent, percentage point, and the two-number trap

Here is a claim with two true forms. A treatment reduces the chance of a bad outcome from 2 in 1,000 to 1 in 1,000. You can report that as a 50 percent reduction in risk, which is the relative risk reduction. You can report it as a fall of 0.1 percentage points, which is the absolute risk reduction. Both are arithmetically correct. They will produce entirely different decisions in a reader.

The convention that keeps you honest is simple: give both, and give the base rate. "The risk falls from 2 in 1,000 to 1 in 1,000, a reduction of half" tells the reader everything in one sentence and takes no more room than the misleading version. The same discipline applies to any percentage change of a percentage. If approval moves from 40 percent to 44 percent, that is 4 percentage points and a 10 percent increase. Writing "approval rose 10 percent" is not false; it is chosen.

In short: Whenever a number is a ratio, name the numerator and the denominator in the sentence, and never let a percentage change of a percentage stand alone.

Why you plot before you summarize

In 1973 the statistician Francis Anscombe published four small data sets in The American Statistician. Each has eleven points. All four have the same mean for x, the same mean for y, nearly the same variance in each variable, the same correlation, and the same fitted regression line to two decimal places. Summarize them and they are identical. Plot them and they are not remotely alike: one is a clean linear relationship, one is a smooth curve that a straight line has no business describing, one is a perfect line with a single outlier dragging the fit, and one is a vertical stack of points at a single x value plus one distant point that creates the entire apparent slope.

Anscombe's point was aimed at statisticians, but it lands on writers too. If you are about to write "there is a strong correlation between deployment frequency and incident rate", look at the scatter first. Half the time the sentence you were going to write turns out to describe one outlier, and the honest sentence is "one team accounts for most of this pattern; excluding them, the relationship is weak."

Choosing the mark, and knowing when not to draw one

The question the reader has	Usual answer	Note
Which category is biggest?	Sorted horizontal bars, zero baseline	Sort by value, not alphabetically, unless the reader needs to look up a specific label
How has this moved over time?	Line chart	A non-zero range is acceptable; label it. Few enough series to label directly
How are these two variables related?	Scatter plot	Show every point. A fitted line without the points hides the shape
What does the spread look like?	Histogram or a strip of individual points	A mean with no distribution behind it can describe a population that contains nobody
What are the exact values?	A table	For fewer than about eight numbers a table is usually clearer, and it is always more accessible

That last row is worth taking seriously. Module 2 argued that a table beats prose when the content is a set of conditions. The same logic runs the other way here: a chart of six numbers is often a picture of a table, and the table would have been faster to read and easier to quote.

The words around the chart

A chart with a title naming its variables has wasted its most-read line. "Response time by month" tells the reader what the axes already say. "Median first response tripled between January and June" states the finding, and a reader who looks at nothing else has still received it. This is the executive summary rule from the previous lesson, applied to a picture.

Underneath it, the caption owes the reader five things, and a chart missing any of them is hard to trust: the source of the data, the period covered, the units, the number of observations behind it, and anything excluded. That last item is the one people leave out, and it is the Challenger lesson in caption form. "Excludes 47 tickets reopened after closure" is a small sentence that changes what the chart means.

Two accessibility obligations carry over from Module 2 and apply to every chart you publish. Do not let colour alone carry a distinction, because a reader with a colour vision deficiency, or anyone printing in greyscale, loses the whole encoding; label the lines directly, or vary the line style as well as the hue. And provide the numbers in text, either as a data table beside the figure or in a description, so a reader using a screen reader gets the same information rather than the phrase "chart of quarterly results".

Worth holding on to: The title states the finding, the caption states the provenance and the exclusions, and the numbers exist somewhere in text. A chart that cannot survive being read aloud is not finished.

Common misconceptions

• If every number is accurate, the chart is honest. Selection, scaling, and framing all mislead without altering a single value. Challenger is the case that proves it.
• All truncated axes are deceptive. Bars encode length and need a zero. Lines encode slope, and a zoomed range is normal and often necessary.
• More data on the chart is more informative. Beyond a few series a reader cannot track lines, and a second axis usually invents a relationship. Split into panels.
• A correlation coefficient describes the data. Anscombe's four sets share a correlation and share almost nothing else. Plot first.
• Percentages are unambiguous. A change of a percentage can be stated in percentage points or as a relative change, and the two produce different decisions from the same fact.
• Choosing the right chart type is the main skill. The main skill is knowing which comparison the reader needs to make. The mark follows from that, and sometimes the answer is a table.

Recap

• Ask what has been excluded from a chart before you check what is on it. Selection on the outcome is invisible and fatal.
• Six everyday distortions, truncated bars, dual axes, area encodings, cherry-picked ranges, counts instead of rates, and perspective effects, all pass a fact check.
• Bars need a zero baseline because they encode length; lines do not, because they encode slope.
• Report a risk change as both a relative and an absolute change, and always name the base rate.
• Plot the points before you describe the relationship; Anscombe's quartet shows why summary statistics are not a description.
• Title the chart with the finding, caption it with source, period, units, sample size, and exclusions, and put the numbers in text so the figure is usable without sight.

Sources

1. Tufte, E. R. (2001). The Visual Display of Quantitative Information (2nd ed.). Graphics Press.
2. Anscombe, F. J. (1973). Graphs in statistical analysis. The American Statistician, 27(1), 17-21. doi.org/10.1080/00031305.1973.10478966
3. Dalal, S. R., Fowlkes, E. B., and Hoadley, B. (1989). Risk analysis of the space shuttle: Pre-Challenger prediction of failure. Journal of the American Statistical Association, 84(408), 945-957.
4. Presidential Commission on the Space Shuttle Challenger Accident. (1986). Report to the President, Volume 1. U.S. Government Printing Office.
5. W3C Web Accessibility Initiative. Images tutorial. w3.org
6. U.S. Bureau of Labor Statistics. Databases, tables and calculators by subject. bls.gov

A regulation about sentence length

The U.S. Army has a regulation on correspondence, AR 25-50, and it does something no employer handbook you will ever receive does: it sets numbers. Sentences should average fifteen words or fewer. Paragraphs should average six sentences or fewer. Prefer short words. Use the active voice. And put the recommendation, the conclusion, or the reason for writing in the first or second paragraph rather than at the end. The standard the regulation sets for a piece of Army writing is that it transmits a clear message in a single rapid reading.

A single rapid reading. Consider what that phrase concedes. It admits that the reader will not read your message twice, will not stop to work out what you meant, and will not send you a note asking for clarification; they will do whatever their best guess suggests, or nothing. An organization that moves people and equipment cannot afford a correspondence culture where meaning is negotiated over three rounds of email, so it wrote the rule down. Your organization has the same problem and has not written it down.

The habit at the centre of that regulation has a name in military and government writing: BLUF, bottom line up front. It is the inverted pyramid from the reports lesson, shrunk to the size of a message, and it is the single change that improves most people's correspondence more than everything else combined.

Bottom line: Write so the message survives one fast reading by a distracted person, because that is the only reading it will get.

The subject line is the document

A large share of your readers will decide what to do based on the subject line and the first line of preview text, and some will act on the subject line alone. Treat it as a headline that must carry the ask and the deadline.

Before	After	What changed
Quick question	Need your sign-off on the vendor contract by Thu 12 Mar	Names the action, the object, and the date
Update	Migration slipping 2 weeks: no action needed, FYI	Says what happened and explicitly releases the reader
Following up	Reminder: 3 outstanding invoices, response needed by Fri	Replaces a social prompt with the actual content
Meeting	Decision needed Tue 10:00: which of 2 vendors, agenda attached	States the decision, so people can prepare or decline
Re: Re: Fwd: Re: project	New thread: Q3 budget shortfall, 40k, options attached	Starting a fresh thread is often the kindest thing you can do

Two conventions worth adopting because they cost nothing. Put a marker in the subject when the message needs no reply, such as FYI or No action needed; readers will thank you for the messages you take off their list. And when a thread has drifted onto a new topic, start a new thread with a new subject rather than replying to a chain whose subject now describes something else entirely.

One email, rewritten

Before, 118 words:

"Hi Priya, I hope you are doing well and that the release went smoothly last week. I wanted to reach out regarding the data retention question that came up in our discussion a little while back, as it has become somewhat more pressing on our end due to some developments with the audit that Legal has been coordinating. I know things are busy, so no rush at all, but if you get a chance at some point it would be really helpful to understand where things stand with the retention schedule and whether there is anything we should be aware of from your side before things move forward. Thanks so much, and let me know if you have any questions."

After, 71 words:

"Hi Priya, I need the data retention schedule for the customer database by Wednesday 12 March. Legal's audit response is due Friday and the schedule is the one item still missing. If the schedule is not final, a draft with the retention periods for the three tables in the attached list is enough, and I will note it as provisional. If Wednesday is not possible, tell me today and I will ask Legal for an extension. Thanks, Sam."

The rewrite is shorter, but length is not the point. Find what the before version never says: what is needed, in what form, by when, and what happens if it does not arrive. The polite hedging did not merely waste words, it deleted the deadline and left Priya unable to prioritize the request against the other eleven in her inbox. Politeness that removes information is not kindness. Notice also that the rewrite offers a fallback, a draft rather than a final, and a path if the date fails. Both of those raise the chance of getting something useful on Wednesday.

So what?: A request without a date is not a request, it is a wish. A request without a fallback forces the reader into all or nothing.

Asking a question so that it can be answered

The most expensive message in any technical organization is the one that triggers a clarification exchange. Five rounds of two-line emails across three time zones can cost a week. A question with a fixed shape avoids most of it.

1. What you are trying to accomplish, in one sentence. Not the sub-problem you got stuck on; the actual goal, because often the answer is that you should not be doing this at all.
2. What you did, specifically enough to be repeated.
3. What happened, quoted exactly. The literal error text, not your paraphrase of it.
4. What you have already ruled out, so the responder does not suggest it.
5. What you need from them, and by when.

Before: "The export isn't working. Any ideas?"

After: "I am trying to produce the monthly billing export for February. Running the export job from the admin console with the date range 1 to 29 February returns after about 40 seconds with the message ERR_TIMEOUT: upstream did not respond within 30000ms. January with the same settings completes in 12 seconds. I have confirmed the credentials are current and rerun it twice with the same result, and the February data loaded normally according to the ingest log. Do you know whether the upstream timeout can be raised for a single job, or should I split the export by week? I need an answer today to bill on time."

The second version is longer and will be answered in one round instead of five. That is the trade, and it is always worth making. Note the exact error string in monospace: paraphrasing an error message is how people end up debugging a problem that does not exist.

Choosing the channel

Channel	Good for	Bad for
Email	A decision or commitment you will need to find again in six months	Rapid back and forth; anything needing more than two people to converge
Chat	Quick unblocking, informal coordination	Anything that must survive; chat history is where decisions go to be forgotten
A shared document	Proposals, specs, anything several people must comment on in place	Urgent requests; nobody is watching the document
A ticket	Work that needs tracking, ownership, and a state	Discussion of whether the work is the right work
A meeting	Disagreement, ambiguity, or anything that has already failed twice in writing	Broadcasting information one person could have written down

One rule that saves whole afternoons: when a written thread reaches its third round without converging, stop writing. The thread is telling you that the disagreement is not about information. Move it to a call, and then write down what was decided and send it to the thread, because otherwise the decision exists only in the memory of the people who attended.

And the small courtesy that is really an efficiency: do not send a message that says only "hi" or "got a minute" and then wait for a reply before asking. It converts one message into three and adds a full round trip of latency to every question. Say hello and ask in the same message.

The sentences that start fights

Three constructions do reliable damage, and they all work the same way: they smuggle an accusation into a statement of fact.

• "As I mentioned in my previous email" and "per my last message". The information content is zero and the message is "you did not read me." If the point needs repeating, repeat it: "The deadline is Wednesday 12 March."
• "Actually, ..." The word adds nothing except the suggestion that the reader was wrong in a way that needed correcting. Delete it and the correction still lands, without the sting.
• "Any update on this?" sent for the third time. Replace it with the consequence: "I need to tell Legal something on Friday. If I do not hear back by Thursday I will tell them the schedule is not available and we are requesting an extension."

Behind all three sits a single test worth applying to anything written in irritation. Assume the message will be forwarded, without warning, to the person it is about, and to that person's manager. This is not a hypothetical caution. Forwarding is one click, and in disputes, litigation, and public records requests, correspondence is exactly what surfaces. Write the version you would be content to see quoted. Then, if you were angry, wait until the next morning and read it again, because the version written at 6 p.m. is almost never the version you still endorse at 9 a.m.

Status updates people actually read

Most status updates are a list of what the writer did, which is the report failure from the previous module in miniature. A reader of a status update wants three things and no others: what changed since last time, what is now at risk, and what the writer needs from them.

Before: "This week the team continued work on the migration. We held several meetings with the vendor and made progress on the schema mapping. Testing is ongoing. We also spent time on documentation and addressed a number of smaller issues that came up."

After: "Schema mapping is done, two weeks late. Cutover moves from 14 March to 28 March. At risk: the finance close on 31 March now has three days of margin instead of seventeen. Need from you: confirmation by Friday that Finance can accept a 28 March cutover, or approval to run the two systems in parallel for a week, which costs about 6,000."

Remember: Nobody reading a status report is grading your effort. They are deciding whether to intervene, and they cannot do that from a list of activities.

Common misconceptions

• Longer, warmer emails are more polite. Hedging usually deletes the deadline and the specific ask, which forces the reader to guess or to write back. Warmth belongs in the greeting, not in the request.
• Putting the ask at the end builds up to it properly. Many readers stop at the preview pane. The ask at the end is an ask that was not made.
• Copying more people covers you. It spreads responsibility until nobody holds it. Address one person by name for the action and copy the rest for information, and say which is which.
• Chat is a lightweight version of email. They differ in what survives. A decision made in chat and never written elsewhere is a decision nobody can find in June.
• You should not repeat yourself. If a point needs to land, repeat the point. What you should not do is announce that you are repeating it.
• A status update should show how hard the team worked. It should show what changed, what is at risk, and what decision is needed.

The short version

• Write for a single rapid reading by a distracted person; that is the standard AR 25-50 sets and the one your readers apply whether or not they say so.
• Bottom line up front. The subject line carries the action and the date; the first sentence carries the request.
• A request needs what, in what form, by when, what happens otherwise, and ideally a fallback.
• A question needs the goal, the steps, the exact error text, what you ruled out, and what you need.
• Match the channel to whether the content must survive, and when a thread hits round three without converging, switch to a call and then write down the outcome.
• Cut the constructions that carry an accusation, and write every message as though it will be forwarded to its subject.
• A status update reports change, risk, and the decision needed, not activity.

Sources

1. Department of the Army. Army Regulation 25-50: Preparing and Managing Correspondence. Army Publishing Directorate. armypubs.army.mil
2. PlainLanguage.gov. Federal plain language guidelines. plainlanguage.gov
3. Digital.gov. Plain language principles. U.S. General Services Administration. digital.gov
4. Nielsen, J. (1996). Inverted pyramids in cyberspace. Nielsen Norman Group. nngroup.com
5. U.S. Securities and Exchange Commission, Office of Investor Education and Assistance. (1998). A Plain English Handbook: How to Create Clear SEC Disclosure Documents.

Nine types of edit, five levels, one budget

In 1980 the Jet Propulsion Laboratory published the second edition of a slim internal document by Robert Van Buren and Mary Fran Buehler called The Levels of Edit. It was not written to make prose beautiful. It was written to solve an accounting problem. JPL's publications group edited documents for engineering projects, the projects paid for the service, and nobody could agree on what had been bought. One project expected a spelling check. Another expected the argument reorganized. Both were billed for editing.

So Van Buren and Buehler enumerated nine distinct types of edit, among them coordination, policy, integrity, screening, format, mechanical style, language, and substantive, and combined them into five named levels. Level 1 applied all nine. Level 5 applied only two. A project could now ask for a Level 3 edit, and both sides knew what would happen to the document and roughly what it would cost.

The framework outlived its accounting purpose because it named something writers keep rediscovering: editing is not one activity. It is several activities that use different kinds of attention and interfere with each other when attempted at once.

Key idea: Before you edit anything, decide which edit you are doing. An editor who has not decided will fix a comma in a paragraph that should not exist.

Three passes, and why one pass fails

Pass	Question it asks	Allowed to change	Forbidden
1. Substantive	Is this the right document, in the right order, for this reader?	Structure, order, headings, what is included, what is cut, what must be added	Nothing is forbidden, but do not polish sentences you may delete in an hour
2. Copyedit	Does every sentence say what it means, consistently?	Grammar, wording, terminology, style guide conformance, cross-references, tables, numbers	Restructuring. If you find a structural problem, note it and keep going
3. Proofread	What is wrong on the page?	Typos, doubled words, broken links, wrong figure numbers, spacing, headers, page breaks	Everything else. This pass is not the place to improve anything

The reason for the separation is attention, not ceremony. Reading for structure means holding the whole document in your head and skimming the sentences. Reading for typos means the opposite: examining the surface so closely that the meaning stops registering. You cannot do both simultaneously, which is why a single combined pass reliably produces a document with an elegant sentence in the wrong section and a doubled word on page four.

One professional habit follows. Proofread last, after layout, and if the document will be printed or converted, proofread the converted artifact rather than the source, because that is where the broken hyphenation and the orphaned heading live.

One paragraph, three passes, three outputs

Here is a notice of the kind an IT department sends. Read it once and try to answer two questions: what must you do, and by when?

Raw draft: "In order to facilitate the enhancement of system security, it has been determined by the Information Security team that a mandatory update to the authentication process will be implemented. All users, effective as of the 1st of April, will be required to utilize two factor authentication when they are logging into the corporate VPN, and it should be noted that failure to enrol prior to this date may result in an inability to access the network. Enrollment can be completed by visiting the the self-service portal, where instructions are provided; users who encounter difficulties should contact the service desk, who are available Monday-Friday. Please note this does not effect access to email."

After pass 1, substantive. The structural problem is that the reader's obligation, and its deadline, sit in the middle of the second sentence behind two clauses of justification. The reason for the change is interesting to the security team and irrelevant to the reader's task. And a set of conditions is buried in prose. So: lead with the action and the date, split the conditions into a list, and move the rationale to the end where anyone who cares can find it.

"Enrol in two factor authentication by 1 April to keep VPN access.

What you need to do: enrol at the self-service portal before 1 April. It takes about five minutes and you will need your phone.

If you do not enrol by 1 April you will not be able to connect to the VPN. Email is not affected.

Help: the service desk is open Monday to Friday.

Why: the Information Security team is requiring a second authentication factor on VPN connections."

After pass 2, copyedit. The structure is now settled, so the second pass looks only at the sentences. It finds: "two factor" needs a hyphen when it modifies a noun, so two-factor authentication; the draft used both enrol and enrollment, and the project style sheet says use the American spellings enroll and enrollment throughout; "effect" should have been "affect", already fixed in pass 1 by luck rather than by the pass that owns it; the date style on this project is 1 April rather than April 1, so that is right; "the service desk" is the name of a team here and the style sheet capitalizes it as Service Desk; and "about five minutes" is a claim nobody has checked, so it needs verifying or removing.

"Enroll in two-factor authentication by 1 April to keep VPN access.

What you need to do: enroll at the self-service portal before 1 April. You will need your phone.

If you do not enroll by 1 April you will not be able to connect to the VPN. Email is not affected.

Help: the Service Desk is open Monday to Friday, 8:00 to 18:00.

Why: Information Security is requiring a second authentication factor on all VPN connections."

After pass 3, proofread. The doubled "the the" from the raw draft is gone, having been removed accidentally during restructuring, which is exactly the kind of luck you should not rely on. What the proofread pass catches now, reading the laid-out page rather than the source: the heading uses a colon in one line and a full stop in another, so the punctuation of the four labels is made consistent; the self-service portal is a link, and its link text reads "here", which fails the accessible-links rule from Module 2; and the times need the same format on both sides of the range.

Three passes, three different classes of finding, and none of them would have been found reliably by one attentive read.

The upshot: The passes are not a courtesy to the writer. They are how you make sure the effort lands on the defect that actually matters first.

What a style guide is for

A style guide exists so that a question gets answered once instead of every time. Should a bulleted list item end in a full stop? Is it email or e-mail? Do you write 5 or five? Left to individual judgment, these get re-decided in every document by every writer, and the inconsistency costs the reader a small amount of attention on every page. That attention is the budget you are protecting.

Guide	Domain	Typical use
The Chicago Manual of Style	Books, scholarly and general publishing	Deep coverage of citation, notes, and the hard cases; the usual fallback when a house guide is silent
AP Stylebook	News and press writing	Journalistic conventions; many corporate communications teams follow it
Microsoft Writing Style Guide	Software and product content	Interface terminology, procedure wording, voice for user-facing text
Google developer documentation style guide	Developer-facing documentation	Code formatting conventions, API reference wording, inclusive terminology
Your house guide	Your organization	Product names, tone, legal and regulatory required wording

The order matters more than the choice. Pick a base guide, then let the house guide override it, then let the project style sheet override that. When a writer asks a style question, the answer is a lookup rather than a debate.

The style sheet does the real work

No published guide will tell you whether your product's feature is called Smart Sync or smart sync. That is what a project style sheet is for: a running document, usually a single page, that records the decisions specific to this project as they are made. It is the highest value per minute of any document in this course.

Entry	Decision	Note
Product name	Atlas Sync, capital A and S, never AtlasSync or Atlas sync	Legal requires the full name on first use per page
sign in vs log in	Verb: sign in. Noun and adjective: sign-in	Matches the interface button
Numbers	Spell out zero to nine; numerals from 10; always numerals with units
Lists	Sentence fragments take no terminal punctuation; full sentences take full stops. Do not mix within one list
Banned terms	Do not use utilize, leverage as a verb, simply, just, easy, obviously	The last four tell a stuck reader that their difficulty is their own fault
Dates	1 April 2026 in prose; 2026-04-01 in tables and file names	Never 04/01/2026, which is ambiguous internationally

That banned-terms row deserves its own moment. "Simply click Export" is a sentence that costs you nothing when the reader succeeds and costs you a great deal when they do not, because you have told them in advance that anyone who struggles here is slow. Cut the word and the instruction is identical.

Rule, or preference?

Some corrections are defensible on grounds of meaning, and some are taste dressed as authority. Knowing which is which will save you from being the editor everyone routes around.

Genuine defects change or obscure meaning: subject-verb disagreement, a dangling modifier ("After sitting overnight, the technician measured the sample" attaches the sitting to the technician), broken parallelism in a list, an unclear antecedent for "it" or "this", a comma splice joining two independent clauses, and a misplaced only ("we only tested three units" against "we tested only three units").

Preferences include the split infinitive, beginning a sentence with And or But, ending a sentence with a preposition, and to a degree the serial comma. The serial comma is a preference with teeth, though, because it occasionally resolves a real ambiguity. "The report thanks our sponsors, the mayor and the fire chief" can be read as thanking two people or four, and one comma fixes it. Pick a convention, record it on the style sheet, apply it consistently, and stop discussing it.

Marking up somebody else's draft

Editing is a social act, and an edit the author resents does not improve the document. Four practices carry most of the load.

• Label severity. Distinguish blocking problems from suggestions. A common convention marks minor points with a prefix such as "nit:" so the author knows they may decline it without argument. An unlabelled pile of comments reads as uniformly obligatory and is exhausting.
• Give the reason or the rewrite, not just the mark. "Unclear" is a complaint. "Unclear which system 'it' refers to here, the gateway or the proxy" is an edit the author can act on in ten seconds.
• State a rule once, then stop. If the author has used the serial comma inconsistently forty times, one comment naming the style sheet entry is better than forty marks, and far better received.
• Leave the voice alone. Change what is wrong, not what is merely different from how you would have written it. If you cannot say which rule a change serves, or what the reader gains, it is a rewrite of somebody else in your own accent.

Common misconceptions

• Editing means correcting grammar. Grammar is one type in one pass. The expensive defects are structural, and they are invisible if you start at sentence level.
• A careful reader can do all three passes at once. Structure requires skimming sentences, proofreading requires stopping at every character. The attention modes exclude each other.
• Spell check has made proofreading unnecessary. It cannot see "the the" across a line break, a correctly spelled wrong word, a broken cross-reference, or a figure numbered twice.
• Style guides are about correctness. They are about not re-deciding. Consistency saves the reader effort; which convention you chose usually does not matter.
• The serial comma is a rule. It is a convention worth adopting because it sometimes disambiguates. Record the choice and stop arguing about it.
• Marking everything shows thoroughness. Unlabelled comments read as equally obligatory. Severity labels are what make a heavy edit survivable.

Putting it together

• The Levels of Edit named nine types of editing so a buyer and an editor could agree on what was being done. Decide which edit you are doing before you start.
• Run three passes: substantive for structure, copyedit for sentences and consistency, proofread for surface defects, in that order, and proofread the final artifact rather than the source.
• Fixing a sentence in a section you will later cut is the most common waste in editing.
• Choose a base style guide, layer a house guide over it, and let a project style sheet override both.
• The style sheet holds what no published guide can: product names, interface verbs, number style, date formats, and banned words such as simply and obviously.
• Separate defects that change meaning from preferences that do not, and settle the preferences once in writing.
• Label severity, give a reason or a rewrite, state a repeated rule once, and leave the author's voice intact.

Sources

1. Van Buren, R., and Buehler, M. F. (1980). The Levels of Edit (2nd ed.). Jet Propulsion Laboratory, California Institute of Technology.
2. University of Chicago Press. The Chicago Manual of Style Online. chicagomanualofstyle.org
3. Microsoft. Microsoft Writing Style Guide. learn.microsoft.com
4. Google. Google developer documentation style guide. developers.google.com
5. PlainLanguage.gov. Federal plain language guidelines. plainlanguage.gov

Two weeks in April 2005

The Linux kernel is written by thousands of people who mostly do not know each other. For three years it was coordinated using a commercial version control system called BitKeeper, made available to kernel developers at no charge. In April 2005 that arrangement ended, and the largest collaborative software project in the world had no way to track who had changed what. Linus Torvalds started writing a replacement in the first days of that month. Within days the new system was managing its own source code, and by the summer it was managing the kernel. He called it Git.

What Torvalds built was not primarily a backup system. It was an answer machine for four questions: what changed, who changed it, when, and why. Every writing team needs those four answers, and almost every writing team that works in email attachments and shared drives cannot produce them. If you have ever opened a folder containing report_final.docx, report_final_v2.docx, and report_FINAL_use_this_one.docx, you have seen a team trying to reinvent version control by hand and losing.

Why this matters: Collaboration problems that feel like personality problems are usually information problems. Nobody can tell what changed, so everybody re-reads everything and nobody trusts the file.

The four questions a shared document must answer

1. Where is the current version? There must be exactly one place, and everyone must know it. Two candidate answers means there is no answer.
2. Who owns the prose? Not who owns the project. Who holds the pen.
3. Who must approve, and for what? Legal approves claims. Security approves what may be published. Engineering approves accuracy. None of them approves your comma placement, and saying so in advance prevents most review pain.
4. What changed since I last read it? A reviewer who has to reread 40 pages to find your three edits will not review carefully the second time.

A team that answers all four in writing before drafting begins will out-perform a more talented team that does not.

One author, many reviewers

There is a persistent confusion between deciding content by consensus, which often works, and writing prose by consensus, which almost never does. A document written by five people in five voices reads like five documents, and the seams are where readers get lost. The workable arrangement is that the group agrees on what is true and what the document must accomplish, and one person writes it.

Name the roles out loud, in the document itself, before the first draft: the author who holds the pen; the reviewers who must comment; the approvers whose sign-off is required and on what specific grounds; and the decider, one named person, who settles disagreements that reviewers cannot resolve. That last role is the one teams skip, and skipping it is why some documents circulate for six weeks. If two senior reviewers want opposite things, no amount of good writing resolves it. Somebody has to choose.

Docs as code, in practice

Module 3 introduced the idea of keeping documentation in version control alongside the code it describes. Here is what that actually looks like at the desk, translated from the habits most writers arrive with.

The shared-drive habit	The version-controlled equivalent	What you gain
Save a copy before big changes	Commit, with a message explaining why	A labelled history you can read and revert to, not a pile of dated files
Work on your own copy so you do not disturb the live one	Work on a branch	The published version stays stable while your draft is unfinished
Email the file around for comment	Open a pull request	Comments attach to specific lines and stay attached as the text changes
Compare two files by reading both	Read the diff	Only what changed, with removals and additions marked
Discover that two people edited the same paragraph	Resolve a merge conflict	The system refuses to guess and shows you both versions
Ask whether the docs match the current release	Require the doc change in the same pull request as the code change	The documentation update becomes part of finishing the work

None of this requires you to become a programmer. Writers on documentation teams routinely use a handful of operations, and the concepts above are most of the value.

Commit messages are documentation

A commit message is read by a colleague in eleven months who is trying to work out why a sentence says what it says. The widely used convention is a short summary line written in the imperative, roughly fifty characters, then a blank line, then the reasoning.

Before: "updates"

Before: "fixed some stuff in the install guide and other changes"

After: "Add memory requirement to install prerequisites" followed by a blank line and: "Three support tickets this month came from installs on machines with 4 GB of RAM, where the service starts and then fails silently under load. Engineering confirmed 8 GB is the real minimum. Adding it to prerequisites rather than troubleshooting, because a reader who gets to troubleshooting has already lost an afternoon."

Notice that the body says why, not what. The diff already shows what changed; nobody needs prose repeating it. Why is the thing that cannot be recovered from the file.

The point: Write the message for the person who will read it after you have forgotten, which within a year includes you.

The formatting habit that makes prose reviewable

Version control systems compare text line by line. If a paragraph is stored as one long line, changing a single word marks the entire paragraph as changed, and the reviewer sees a wall of red and green and cannot find your edit. This is the main reason writers find document diffs useless, and it is entirely fixable.

The fix is to break lines at sentence boundaries, or at clause boundaries in long sentences, and let the rendering engine reflow them into paragraphs. Readers of the published document see no difference; a line break in the source becomes a space in the output. Reviewers see everything.

	Source stored as	What the diff shows after you change one word
One long line	The whole paragraph on a single line	The entire paragraph removed and the entire paragraph added
One sentence per line	Each sentence on its own line	One line removed, one line added, the changed word visible inside it
Wrapped at a fixed width	Lines broken at, say, 80 characters	Every line from the edit to the end of the paragraph appears changed, because the wrapping shifted

That third row is why hard-wrapping at a fixed column, a habit inherited from plain-text email, is worse than either alternative for collaborative prose: a single inserted word reshuffles every subsequent line and produces a diff that looks like a rewrite.

What a merge conflict is, and how to read one

A conflict happens when two people change the same lines and the system will not guess which version wins. It marks the region and hands it to a human. The markers look like this.

Marker line	Meaning
Seven less-than signs followed by HEAD	Everything below this line, down to the divider, is the version already on your branch
Seven equals signs	The divider between the two versions
Seven greater-than signs followed by a branch name	Everything above this line, up to the divider, is the version coming in

Resolving it means deciding what the text should say, deleting all three marker lines, and leaving one correct version. Two mistakes are common. The first is keeping both versions because both look reasonable, which produces a paragraph that says the same thing twice in slightly different words; readers notice, and it is embarrassing. The second is resolving a conflict in content you do not understand. If the incoming change came from an engineer who corrected a technical claim, and you keep your version because you preferred the sentence, you have quietly reintroduced a factual error. Ask.

Worth holding on to: A conflict is not a failure of the tool. It is the tool declining to make an editorial decision on your behalf.

Review comments that produce a change

Google's published guidance for code review contains a standard that transfers to documents almost word for word: the reviewer approves once the change definitely improves the document overall, rather than holding out until the document is perfect. Perfection is not on the table; the alternative to a good change is usually not a better change but no change and a stalled author.

Three rewritten comments show what actionable looks like.

Before	After
This section is confusing.	I lost the thread at the second paragraph: it is not clear whether the retry happens automatically or the user triggers it. Which is it?
Wrong.	Blocking: the default timeout is 30 seconds, not 60. Source: the config reference. This matters because the example below assumes 60 and will not reproduce.
I would have written this differently.	Nit, take it or leave it: I would put the prerequisites before the overview, since a reader without the API key cannot use either section.

Each rewrite does the same three things: it names the specific location, it says what is wrong or unclear rather than only that something is, and it labels how strongly the reviewer feels. The third one explicitly gives permission to decline, which is what keeps a review from becoming a negotiation.

One more discipline. Comment on a version, not on a moving target. If the author is editing while five reviewers comment, half the comments will be answered by changes already made and the author will spend the day writing "already fixed". Freeze, review, revise, repeat.

Common misconceptions

• Version control is for programmers. It answers what changed, who changed it, when, and why, which is a writing team's problem before it is a programming one.
• A good document can be written by a committee. Decide content by consensus if you like; give the prose to one person. Five voices produce seams a reader falls through.
• More reviewers means better review. Past a handful, each reviewer assumes the others are being careful. Name the reviewers and say what each is responsible for.
• Track changes in a word processor is equivalent. It records edits within one file. It does not give you branches, a readable history of why, or a way to keep two versions alive at once.
• A merge conflict means somebody did something wrong. It means two people edited the same lines, which is normal. The system is refusing to make an editorial choice without you.
• The reviewer should hold out for the best possible version. The realistic comparison is against the current document, not against an ideal one. Approve improvements and file the rest separately.

Where this leaves us

• Git was written in April 2005 to answer four questions at scale: what changed, who, when, and why. Those are a writing team's questions too.
• Before drafting, settle where the single current version lives, who holds the pen, who approves what, and how a reviewer sees only what changed.
• Name a decider. Documents stall when two senior reviewers disagree and nobody has authority to choose.
• Commit messages explain why, in the imperative, because the diff already shows what.
• Break source lines at sentence boundaries so a one-word change produces a one-line diff. Fixed-width wrapping is the worst option for prose.
• A merge conflict is a request for an editorial decision. Never keep both sides, and never resolve content you do not understand.
• Good review comments name a location, state the specific problem, and label severity so the author knows what may be declined.

Sources

1. Chacon, S., and Straub, B. Pro Git (2nd ed.). Apress. git-scm.com
2. Git project. Git documentation. git-scm.com
3. Google. Google engineering practices documentation: how to do a code review. google.github.io
4. Write the Docs. Docs as code. writethedocs.org

One word, one meaning

In the 1980s European airlines had a maintenance problem that was not mechanical. Aircraft manuals were written in English, and a large share of the people servicing the aircraft did not speak English as a first language. Misreadings of maintenance procedures are not a matter of style. The industry body that became ASD produced a controlled subset of English for the purpose, and it is now maintained as the specification ASD-STE100, Simplified Technical English.

What makes it interesting is how strict it is. There is an approved dictionary of roughly a thousand words, and each approved word carries one approved meaning and one part of speech. If a word has three senses in ordinary English, at most one survives, and the others must be expressed some other way. Procedural sentences are held to about twenty words and descriptive sentences to about twenty-five. Noun clusters are limited. The active voice is required in procedures. Articles that ordinary technical prose drops must be restored, because "remove filter cover plate" can be parsed several ways and "remove the cover plate from the filter" cannot.

You are probably not writing aircraft manuals. But the constraints of Simplified Technical English are a map of exactly where English breaks for a reader who learned it second, and that map is useful whether your text will be translated, machine translated, or simply read in Manila and Munich.

The core of it: Writing for a global audience is not a matter of tone or politeness. It is the removal of specific constructions that are ambiguous the moment the reader cannot lean on native intuition.

Two different jobs with similar names

	Internationalization	Localization
What it is	Designing the content and the product so it can be adapted without rebuilding	Adapting it for one specific place and language
When it happens	Before there is a second language	Once per target locale
Writer's part	Unambiguous source text, no assembled sentences, no text baked into images, room for expansion	Reviewing translated output, maintaining the glossary, resolving translator queries
Cost of skipping it	Every locale pays for the same defect, forever	One locale reads badly

The asymmetry in that last row is the practical argument. An ambiguity in your English source is not translated once. It is sent to twenty translators, each of whom guesses, and roughly half of them guess differently from you.

Constructions that become ambiguous in translation

Problem	Before	After
Phrasal verbs	Once the job has run, check that the file did not get cut off.	After the job finishes, check that the file is complete.
Dropped relative pronoun	The file you selected cannot be opened.	The file that you selected cannot be opened.
Noun stack	Server backup failure notification settings	Settings for notifications about failed server backups
"May" with two senses	Users may submit the form after review.	Users are allowed to submit the form after review. (Or: Users might submit it, if that was the meaning.)
"Once" with two senses	Run the script once the export completes.	Run the script after the export completes.
Verb or noun	Cleaning the filter is required weekly.	You must clean the filter every week.
Ellipsis	Enable logging and the debug console.	Enable logging and enable the debug console.
Negative question	Do you not want to receive updates?	Do you want to receive updates?
Idiom and culture-bound reference	This should be a home run for most teams.	This works well for most teams.

The negative question row is worth dwelling on, because the failure is not merely stylistic. Answering "no" to "Do you not want updates?" means "no, I do not want them" in English and, in the intuition of many speakers of other languages, "no, that is not correct, I do want them." The same trap appears in interface checkboxes labelled with a negative, such as "Do not send me messages". Phrase the option positively and let the checkbox state carry the negation.

What matters here: Every construction above is perfectly good English. That is the point. Fluency is not the test; unambiguity for a reader without native intuition is.

Formats that break at the border

Element	The assumption	What to do
Dates	03/04/2026 is 3 April, or is it 4 March?	Use ISO 8601, 2026-04-03, in tables and data. In prose, spell the month: 3 April 2026
Decimal separator	1,500 means one thousand five hundred	In much of Europe the comma is the decimal point, so 1,500 reads as one and a half. State units and avoid ambiguous grouping in critical values
Digit grouping	Groups of three	South Asian conventions group differently. Never hard-code grouping into a translatable string
Time	3:00 pm is clear	Much of the world uses a 24-hour clock. Write 15:00, and give the time zone
Names	A given name then a family name, both in Latin script	Order varies, some people have one name, some have several family names. Use a single full-name field where you can, and never require a middle initial
Addresses and postcodes	The local template with a two-letter state	Allow free-form address lines and postcodes containing letters, spaces, or nothing at all
Units	The reader knows what 68 F feels like	Give SI units, or both. Mars Climate Orbiter, from Lesson 1, is the extreme version of this failure
Sorting	Alphabetical order is alphabetical order	Collation rules differ by language, so do not promise an ordering the software cannot honour

Text grows, and layouts do not

Translated text is usually longer than its English source, and the effect is worst exactly where you have least room. W3C's guidance on this makes the key point: short strings expand proportionally far more than long ones, so a single-word button label can grow to several times its original width while a paragraph might grow by a fifth. A navigation bar that fits perfectly in English will overflow, truncate, or wrap into two lines in German or Finnish.

Three habits handle almost all of it. Do not size containers to the English string. Do not put text inside images, because an image cannot be translated without a designer and will silently stay in English forever. And write labels that can grow: "Save" is a better button label than a clever three-word phrase, because it has somewhere to expand into.

The sentence assembled at runtime

This is the single most expensive mistake a writer can make in software text, and it usually starts as a reasonable-looking economy. Somebody writes one message and inserts pieces:

Before: the string "You have deleted " followed by a number, followed by " files."

It breaks in at least three ways. Many languages put the verb elsewhere, so the fragments cannot be reassembled in that order. Plural rules differ: some languages have one form, English has two, and several Slavic languages have three or more, chosen by the value of the number. And a translator handed the fragment "You have deleted " in isolation has no idea what follows it or what gender or case the following noun takes.

After: one complete message per plural form, each carrying a named placeholder, and delivered to the translator as a unit. In English: {count} file deleted and {count} files deleted, tagged as the singular and plural forms of one message, so a locale with six forms can supply six.

The writer's rule is short: never split a sentence across two strings, and never let a placeholder be the first thing a translator sees without context.

What a translator needs from you

• Context for every string. "Open" is a verb on a button and an adjective in a status. Say which. A note attached to the string costs you ten seconds and saves a wrong translation in every locale.
• A glossary, with the terms that must never vary. Product names, interface labels, safety terms. This is the style sheet from the previous lesson, doing a second job.
• Consistency in the source. Translation memory reuses previously translated segments. If you wrote "Select the file" in one place and "Choose the file" in another to avoid repetition, you have just paid twenty times for a synonym nobody wanted. The Module 1 rule about naming the same thing the same way turns into a line item on an invoice.
• Reachable answers. Translators raise queries. If nobody answers them, they guess, and you find out in a support ticket.

Machine translation changes the economics but not the obligations. Neural systems do markedly better on source text that is consistent, unambiguous, and free of the constructions in the table above, so writing for translation is now also writing for the machine. What has not changed is the review requirement. For marketing copy, a machine draft with light editing may be fine. For safety warnings, dosage instructions, legal notices, or anything where a wrong reading injures somebody, an unreviewed machine translation is not a cost saving. It is an unexamined liability written in a language nobody on your team can read.

In short: Good source text is the cheapest possible investment, because every defect in it is bought once and paid for in every language.

Common misconceptions

• Writing for translation means writing simply. It means writing unambiguously. A long precise sentence translates better than a short idiomatic one.
• Translation is the last step. The decisions that make translation possible, whole strings, no text in images, room for expansion, are made while you write, and cannot be retrofitted cheaply.
• Varying your wording keeps prose lively. In translated content, every synonym is a new segment to translate and a new chance to diverge. Repetition is the correct choice.
• English is the safe common language, so ambiguity does not matter much. Second-language readers cannot fall back on native intuition, which is exactly what resolves phrasal verbs and dropped relative pronouns.
• Machine translation has made this obsolete. It has raised the reward for clean source text and left the review obligation for safety-critical content untouched.
• Only the words need localizing. Dates, decimals, name fields, sorting, and layout width all break, and each one breaks silently.

What to remember

• Simplified Technical English exists because aircraft maintenance in a second language failed on ambiguity, and its rules map where English is fragile: one meaning per word, short sentences, restored articles, no noun stacks, active voice in procedures.
• Internationalization is what you do once so adaptation is possible; localization is what you do per locale. Source defects are paid for in every language.
• Cut phrasal verbs, dropped relative pronouns, noun stacks, ambiguous may and once, ellipsis, negative questions, and idiom.
• Dates, decimal separators, clocks, names, addresses, units, and sorting all carry local assumptions. ISO 8601 for machine-facing dates; a spelled month in prose.
• Translated text expands most where strings are shortest, so never size a container to the English label and never put text in an image.
• Never assemble a sentence from fragments; ship complete messages with named placeholders and proper plural forms.
• Give translators context, a glossary, consistent source, and an answer when they ask; and never ship an unreviewed machine translation of safety-critical text.

Sources

1. ASD. ASD-STE100: Simplified Technical English. AeroSpace and Defence Industries Association of Europe. asd-ste100.org
2. W3C. Internationalization. World Wide Web Consortium. w3.org
3. W3C. Personal names around the world. w3.org
4. International Organization for Standardization. ISO 8601 date and time format. iso.org

A name for interfaces that trick people

In 2010 a British user-experience designer named Harry Brignull began cataloguing interfaces built to make people do things they had not chosen to do, and gave the practice a name that stuck: dark patterns, now more often called deceptive design. Twelve years later, in September 2022, the staff of the U.S. Federal Trade Commission published a report called Bringing Dark Patterns to Light, sorting the tactics into families: design that induces false beliefs, design that hides or delays material information, design that leads to charges the customer did not authorize, and design that obscures privacy choices.

Read that list again with a writer's eye. Not one of those categories requires a false sentence. A subscription page can state the price, the renewal terms, and the cancellation policy with complete accuracy, and still be built so that almost nobody who signs up understands what they agreed to. The price is in the heading. The renewal is in grey nine-point type below the fold. The cancel link is four screens deep behind a button that says "No thanks, I like paying full price."

This is the uncomfortable centre of the whole subject, and it is why ethics is the last lesson in this course rather than a paragraph in the first. Every technique you have learned here is a technique for controlling what a reader notices, understands, and does. Headings direct attention. Placement decides what gets read. Plain language makes a fact land. Design makes an option findable or invisible. A person who is good at those things is, by construction, good at the inverse.

Why this matters: Skill in technical communication is not ethically neutral, because the skill is influence over what a reader knows. The only question is what you do with it.

Five ways a true document deceives

Move	How it works	Example
Omission	Everything stated is true; the decisive fact is absent	The Challenger charts from Lesson 10, showing damaged flights and not clean ones
Placement	The material fact is present, where nobody will be reading	Automatic renewal terms below the fold, after the sign-up button
Emphasis	Type size, contrast, and order decide what registers	A bright Accept button beside a grey, low-contrast Decline of the same importance
Framing	The true number is chosen from several true numbers	A 50 percent risk reduction that is 0.1 percentage points
True but irrelevant	Accurate content crowds out what the reader needed	A safety notice that leads with regulatory citations and reaches the hazard on page two

The defence people reach for is always the same: "everything in it is accurate." Accuracy is a floor, not a ceiling. The working test is different and harder. Would this reader, having read the document as it is actually laid out, be surprised later by something you knew at the time of writing? If yes, the document deceived them, whatever its sentences said.

Design that argues

Pattern	What it does	The honest version
Pre-checked consent box	Converts inaction into agreement	Leave it unchecked. Consent that required no action was not given
Confirmshaming	Labels the decline option so refusing feels like an admission	Two neutral labels of equal weight: Subscribe and Not now
Contrast asymmetry	Makes one of two equal choices hard to see	Equal visual weight for options of equal consequence
Asymmetric effort	One click to subscribe, six screens to cancel	Cancellation no harder than sign-up, by the same route
Buried disclosure	Puts the material term where scanning readers never go	Material terms next to the action they govern, in the same type size
Roach motel forms	Requires a phone call to undo what a form began	Undo by the channel that did it
Countdown pressure	Manufactures urgency to prevent reading	If the deadline is real, state it plainly; if it resets on reload, it is a lie told with a clock

Two of these have moved from ethics into law in some jurisdictions. In the United States, the Restore Online Shoppers' Confidence Act requires clear and conspicuous disclosure of the material terms of an automatically renewing offer before billing information is taken, and a simple way to stop the charges. Notice what that legal standard is really about. It is not a rule about truth, since the terms were disclosed in the deceptive version too. It is a rule about placement and prominence, which is to say a rule about document design, enforced because design was being used to defeat disclosure.

The grammar of avoiding blame

Module 1 taught the passive voice with a deleted actor as a plain-language defect. Here it appears in its other role, as the standard instrument for describing a harm without an agent. Read this, which is close to the house style of a whole industry.

Before: "We are writing to inform you of an incident that may have involved some of your information. On or about 14 March, an unauthorized third party gained access to a system containing certain customer records. Upon discovery, steps were taken to secure the environment and law enforcement was notified. While we have no evidence that your information has been misused, out of an abundance of caution we are offering complimentary credit monitoring. We value your trust and apologize for any inconvenience this may cause."

After: "Someone stole your name, address, date of birth, and Social Security number from us on 14 March. We did not notice until 2 April, and we closed the hole that day. We do not know whether the data has been used, and we will not be able to find out. What to do now: freeze your credit with all three bureaus. Phone numbers and step-by-step instructions are on page 2. We are paying for two years of credit monitoring; your enrolment code is on page 2 and must be used before 31 December. This happened because of a failure on our side."

Go through the evasions the rewrite removes, one at a time, because each is a technique you will be asked to use. "An incident that may have involved some of your information" names nothing: not the data, not the reader's data specifically, not the theft. "Steps were taken" has no actor. "Upon discovery" conceals a nineteen-day gap between the breach and its detection, and the reader has a right to that number because it bears on how long their data was exposed. "Out of an abundance of caution" reframes a remedy as generosity. "Complimentary" does the same. "We have no evidence that your information has been misused" is true and is very close to meaningless, because the company has no way of gathering such evidence; the honest version says so. And "any inconvenience this may cause" is the sentence to watch for in your own drafts. Identity theft is not an inconvenience, and the phrase performs regret while denying the size of the harm.

The core of it: Passive voice, nominalization, and euphemism are not always evasions. But when the missing actor is you, and the missing number is unflattering, that is exactly what they are.

Nobody reads the terms, and what that obliges you to do

In 2008 Aleecia McDonald and Lorrie Faith Cranor did an arithmetic that has never stopped being cited. They estimated how long it would take an average American internet user to read the privacy policy of every website they visited in a year, and arrived at roughly 201 hours, with a national opportunity cost they put in the hundreds of billions of dollars. Nobody has ever suggested people should therefore read faster. The number is evidence about a system, not about readers.

Here is the ethical consequence for a writer, and it is sharper than it first appears. If you know, as a matter of established fact, that the reader will not read the twenty-page agreement, then placing a material term there is not disclosure. It is a decision to be technically compliant and practically silent. You cannot claim both that the terms are important enough to bind the reader and that it is fine to present them in a form you know will not be read.

The workable answer is the layered notice: a short surface notice carrying the handful of facts that would change a reasonable person's decision, in the same type size as everything around it, next to the action it governs, with the full terms underneath for anyone who wants them. Test the layer, not the document. Show the surface notice to five people, ask them what they just agreed to, and count how many get the renewal term right.

The warning that satisfies a lawyer and the warning that works

Module 3 gave the structure of an effective warning: what the hazard is, what happens, and what to do, placed before the step where the harm can occur. The ethical version of that lesson is a question about purpose. A warning can be written to reduce injury, or it can be written to establish that the reader was told. These produce different documents. The second one is comprehensive, is placed in a block on page one, uses the vocabulary of liability, and is skipped by every reader. It performs its function perfectly, and its function is not safety.

You can usually tell which you are looking at by asking a single question: was it ever tested on anyone who was not a lawyer? A warning that has never been put in front of a user is not a safety measure. It is a legal artifact that happens to be printed in a user manual.

When you are asked to write it

Most of the time nobody will ask you to lie. You will be asked to move a disclosure, soften a verb, drop a number, or make a button less findable, and each request will be small and reasonable-sounding and will arrive from somebody more senior than you. Some practical moves, roughly in order of cost.

1. Ask in writing, neutrally. "Just to confirm: you would like the renewal terms moved from beside the button to the linked terms page?" A surprising share of these requests do not survive being written down, because the person making them had not framed it that way to themselves.
2. Name the harm and who bears it, specifically. Not "this feels misleading" but "a customer who reads only this page will not know they are being charged again in twelve months, and we will see it as chargebacks and cancellations in month thirteen." Concrete harm, in the organization's own units, is what makes the argument legible.
3. Offer the compliant alternative. You are far more effective arriving with a version that is both honest and achieves the legitimate goal than with an objection. Most deceptive design exists because it was easier, not because deception was the aim.
4. Escalate to the function that owns the risk. Legal, compliance, privacy, and security teams frequently have both the authority and the motive to stop something you cannot.
5. Keep a record. Note what you were asked, what you said, and what was decided. This is not an act of hostility; it is what lets you be accurate later, which protects you and the organization both.
6. Know your own line in advance. Decide, before the moment arrives, what you would refuse to write. People who have not decided in advance rarely refuse in the moment.

It would be dishonest to end that list without saying what it costs. A junior writer has limited power and real exposure, and the advice to simply refuse is easy to give from outside. Steps one to three are available to almost everybody and are effective more often than you would expect. Steps four to six carry risk that only you can weigh.

The professional codes exist partly to make that weighing less lonely. The Society for Technical Communication publishes ethical principles for technical communicators; the ACM and IEEE publish codes of ethics that bind members of those professions. Their practical value is not that they settle hard cases, because they do not. It is that they establish, in public and in advance, that "I was asked to" is not a complete account of why a document says what it says.

Bottom line: The document has your name on the change history. Write the version you would be willing to explain.

Common misconceptions

• If every sentence is true, the document is honest. Omission, placement, emphasis, framing, and relevance all deceive without a false statement. Accuracy is the floor.
• Deceptive design is a designer's problem, not a writer's. Button labels, headings, disclosure text, and where a term sits on the page are all writing decisions.
• Disclosure in the terms of service counts as telling the reader. If you know the reader will not read it, placing a material term there is a decision to be compliant and silent.
• Passive voice is always an evasion. It is fine when the actor is unknown or irrelevant. It becomes an evasion when the missing actor is you.
• Softer language is kinder to the reader receiving bad news. Vagueness in a breach notice removes the information a reader needs to protect themselves. Directness is the kindness.
• Ethics is about refusing. Most of the work is asking in writing, naming the harm concretely, and arriving with a version that is honest and still achieves the goal.

Looking back

• Deceptive design was named in 2010 and catalogued by the FTC in 2022, and almost none of it requires a false statement.
• Five moves deceive while remaining true: omission, placement, emphasis, framing, and burying the needed fact under accurate irrelevance.
• The test is not whether the sentences are accurate but whether the reader will later be surprised by something you knew while writing.
• Pre-checked boxes, confirmshaming, contrast asymmetry, asymmetric effort, and buried disclosures all have honest equivalents that cost nothing but a decision.
• Watch the agentless passive, the nominalization, and the euphemism whenever the missing actor is your own organization.
• Since readers demonstrably do not read long agreements, material terms belong in a short layered notice beside the action, and that notice should be tested on real people.
• A warning written to prove the reader was told is a different document from a warning written to prevent harm, and only one of them gets tested.
• When asked to write something deceptive: confirm in writing, name the harm concretely, bring the honest alternative, escalate to the function that owns the risk, keep a record, and know your line before you need it.

Sources

1. U.S. Federal Trade Commission. (2022). Bringing Dark Patterns to Light. Staff report. ftc.gov
2. Brignull, H. Deceptive design. deceptive.design
3. McDonald, A. M., and Cranor, L. F. (2008). The cost of reading privacy policies. I/S: A Journal of Law and Policy for the Information Society, 4(3), 543-568.
4. Society for Technical Communication. Ethical principles for technical communicators. stc.org
5. Association for Computing Machinery. ACM Code of Ethics and Professional Conduct. acm.org
6. IEEE. IEEE Code of Ethics. ieee.org