Technical Writing on emsenn.net

Audience and Task Analysis

Fri, 06 Mar 2026 00:00:00 +0000

Assumed audience

Reading level: comfortable writing prose; new to writing documentation for others.
Background: has written essays or reports but not procedural documentation or reference material for unfamiliar readers.
Goal: learn to analyze an audience and organize documentation around the reader’s tasks.

The fundamental problem

Technical writing exists because someone knows something another person needs. The writer’s job is to close that gap. The difficulty is that the writer, by definition, stands on the far side of the gap — they already understand the material, and this understanding makes it hard to see what a reader who doesn’t understand it actually needs.

Clear Prose and the Paramedic Method

Fri, 06 Mar 2026 00:00:00 +0000

Assumed audience

Reading level: comfortable writing documentation; has completed “Audience and Task Analysis” and “Information Architecture for Documents.”
Background: understands audience analysis and document structure.
Goal: learn to revise prose at the sentence level so that documentation is not just well-organized but well-written.

The Official Style

Richard Lanham named the Official Style: the bloated, nominalized prose characteristic of bureaucracies, institutions, and academia [@lanham2006]. Its hallmarks are:

Nominalizations: turning verbs into nouns. Implement becomes the implementation of. Decide becomes the decision was made to. The action disappears into an abstraction.
Prepositional pile-up: chains of of, in, for, by, with phrases. “The implementation of the configuration of the settings for the management of user access” — five prepositions, zero clarity.
Passive voice without purpose: “The system was configured” rather than “We configured the system.” Passive voice has legitimate uses (when the agent is unknown or irrelevant), but in the Official Style it serves to hide who did what.
Throat-clearing: “It is important to note that,” “There are several factors that should be taken into consideration,” “It should be pointed out that.” These delay the sentence’s content without adding meaning.

The Official Style is not a deliberate choice. It is the default register of institutional writing — the way people write when they’re writing as a role (engineer, manager, academic) rather than as a person communicating with another person.

Information Architecture for Documents

Fri, 06 Mar 2026 00:00:00 +0000

Assumed audience

Reading level: comfortable writing documentation; has completed “Audience and Task Analysis.”
Background: understands audience analysis and task analysis.
Goal: learn to organize documents so readers can find and use the information they need.

Readers don’t read — they scan

Technical documents are not read from beginning to end. Readers scan for the section relevant to their current task, read that section, and leave. Janice Redish argued that web content should be treated as a user interface — readers interact with it the way they interact with software, and the same usability principles apply [@redish2012].