emsenn

Technical Writing

9 min read

This folder has content about technical writing, the craft of making complex information usable. Technical writing produces documentation, reference material, tutorials, specifications, and instructional content. Its defining concern isn’t the subject matter — any discipline can require technical writing — but the relationship between writer, material, and reader: the writer knows something the reader needs, and the writing exists to close that gap.

David Dobrin argued that technical writing is defined not by its topic but by its accountability to shared methods of verification: “technical writing is writing that accommodates technology to the user” [@dobrin1983]. Technical writing succeeds when the reader can do what they couldn’t do before reading it — or understand what they couldn’t understand. A poem succeeds when it creates an experience; an essay succeeds when it develops an argument; technical writing succeeds when it’s useful.

Methods

Technical writing’s methods draw on rhetoric, cognitive psychology, and document design. The core methods are:

  • Audience analysis — determining what the reader knows, what they need, and what they’re trying to do. Karen Schriver distinguished three approaches: classification-based (demographics), intuition-based (imagining the reader), and feedback-based (testing with real readers). Her empirical research showed that writers systematically overestimate how well readers understand their text — only feedback-based methods reliably reveal comprehension failures [@schriver1997]. The plain language specification defines a default audience; technical writing for specialized readers declares its assumed audience explicitly.

  • Task analysis — breaking a process into steps the reader can follow. Steps must be ordered by dependency, not by the writer’s reasoning process. Linda Flower called the failure to reorder “writer-based prose” — text organized around the writer’s discovery rather than the reader’s need [@flowerhayes1981].

  • Information architecture — organizing content so the reader can find what they need. Headings, cross-references, and progressive disclosure serve this goal. The content types in this vault — term definitions, concept notes, lessons — are genres in Carolyn Miller’s sense: typified responses to recurring rhetorical situations [@miller1984]. The design module’s information architecture discipline develops these principles in depth.

  • Sentence-level clarity — Joseph Williams demonstrated that clear sentences put characters in subject position and their actions in verbs. When writers nominalize actions (“the implementation of the system” instead of “we implemented the system”), readers work harder for less understanding — the Official Style that Richard Lanham named and diagnosed [@williams2006]. Lanham’s Paramedic Method operationalized this into a repeatable revision procedure [@lanham2006].

  • Usability testing — watching real readers use the document and revising based on where they hesitate, misread, or fail. Karen Schriver’s protocol-aided audience analysis provides the most rigorous form: think-aloud protocols where readers verbalize their thought process while using a document [@schriver1997]. Janice Redish argued that content should be tested the same way software is tested — through observation, not self-report [@redish2012]. The plain language specification’s paraphrase test and task test are simplified versions.

Content types

Technical writing in this vault appears as:

  • Term definitions — compact, precise answers to “what does this mean?” See the style guide’s term definition conventions.
  • Concept notes — broader explorations of “how does this work?” See the style guide’s concept note conventions.
  • Lessons — guided paths from not-understanding to understanding. Lesson design follows backward design principles [@wigginsmctighe2005] and manages cognitive load by introducing one concept at a time [@sweller1988]. See the pedagogy module’s lesson design curriculum.
  • Specifications — precise statements of how a system should behave. Specifications prioritize completeness and unambiguity over readability, but plain language still applies where it doesn’t conflict.
  • Index pages — navigation aids with enough context to orient the reader.

Key principles

  1. The reader’s task comes first. Structure content by what the reader needs to do, not by what the writer knows. This is the shift from writer-based to reader-based prose [@flowerhayes1981].
  2. Concrete before abstract. Show the thing, then name it. Richard Mayer’s multimedia learning research found that learners build understanding from examples to principles, not the reverse [@mayer2009].
  3. One idea per unit. A section, paragraph, or definition should have one job. This follows from cognitive load theory: working memory is limited, and each additional concept competes for processing capacity [@sweller1988].
  4. Don’t tell the reader how to feel. Present the material. “This powerful feature” is editorializing; “this feature” is technical writing. George Orwell identified this as a general principle: “never use a metaphor, simile, or other figure of speech which you are used to seeing in print” [@orwell1946].
  5. Test with readers. If the reader can’t use the document, the document doesn’t work, regardless of how correct it is [@schriver1997].

Key texts

  • John Carroll, The Nurnberg Funnel [@carroll1990] — minimalist documentation: task-oriented, stripped-down materials outperform comprehensive manuals
  • Joseph Williams, Style: Lessons in Clarity and Grace [@williams2006] — sentence-level clarity as characters, actions, cohesion, and coherence
  • Karen Schriver, Dynamics in Document Design [@schriver1997] — empirical research on how readers actually process documents
  • Janice Redish, Letting Go of the Words [@redish2012] — web content as user interface, usability testing for writing
  • Richard Lanham, Revising Prose [@lanham2006] — the Paramedic Method for cutting bureaucratic prose
  • Carolyn Miller, “Genre as Social Action” [@miller1984] — genres as typified rhetorical actions, not formal templates
  • Linda Flower and John Hayes, “A Cognitive Process Theory of Writing” [@flowerhayes1981] — writing as recursive cognitive process
  • Kristina Halvorson, Content Strategy for the Web [@halvorson2012] — content strategy as the governance layer over content creation
  • Mike Markel and Stuart Selber, Technical Communication [@markel2021] — standard textbook covering audience analysis, document design, usability, and ethics
  • Rudolf Flesch, The Art of Readable Writing [@flesch1949] — readability research and plain language advocacy
  • George Orwell, “Politics and the English Language” [@orwell1946] — the relationship between clear language and clear thought

Key thinkers

Contemporary concerns

Technical writing is not only a matter of clarity and usability. Contemporary scholarship identifies several dimensions that classical treatments underdevelop:

Accessibility. Technical documents must be usable by people with the widest possible range of abilities — those using screen readers, readers with cognitive differences, readers in high-stress situations. Accessibility goes beyond readability: structural headings, alt text, simple tables, and clear link text are writing concerns, not just design concerns [@dolmage2017] [@oswal2019]. The plain language specification’s existing rules (clear headings, short sections, descriptive links) already serve accessibility; the gap is in explicitly addressing assistive technology and cognitive diversity.

Social justice. Natasha Jones argues that technical communication is never neutral — documentation practices carry assumptions about whose needs matter and whose knowledge counts [@jones2016]. Asao Inoue’s work on writing assessment shows how standards of “quality” can reproduce inequity when applied without examining whose language they center [@inoue2015]. Technical writers make consequential choices about what to document, for whom, and in what language — choices that shape access to systems, services, and rights.

Multimodal composition. Technical documentation increasingly combines text with code, images, video, and interactive elements. Kathleen Blake Yancey argued that composition must expand beyond alphabetic text [@yancey2004]. Stacey Pigg’s research shows how professional writing now occurs across fragmented digital environments [@pigg2014]. For this vault — a text-based system with Markdown, cross-references, and embedded images — the relevant question is how to compose effectively within the available modes.

Translingual awareness. Technical documentation increasingly serves multilingual audiences and operates in multilingual environments. Translingual approaches treat language difference as a resource rather than a problem, and challenge the assumption that a single standard language is the only medium for clear communication [@canagarajah2013].

Relation to other writing disciplines

Technical writing draws on the same sentence-level skills as all writing in this vault — the style guide governs grammar, voice, and word choice across disciplines. What distinguishes technical writing is its structural concern: how to organize information so a reader with a specific need can find and use it.

The plain language specification is the operational foundation for technical writing in this vault. The pedagogy module’s lesson design and curriculum design curricula extend these principles to educational content specifically. The connection is direct: Paulo Freire’s distinction between the banking model and problem-posing education applies to technical writing as much as to teaching. A reference document that opens with definitions and expects the reader to absorb them reproduces the banking model in written form. A lesson that opens with a concrete situation and builds understanding through engagement is problem-posing. Both are legitimate content types, but the distinction matters for choosing between them.

Grant Wiggins and Jay McTighe’s backward design [@wigginsmctighe2005] applies directly to technical writing: start from what the reader should be able to do after reading, then determine what evidence would show they can do it, then plan the content. This reversal prevents the most common failure mode in technical writing — organizing content around what the writer knows rather than what the reader needs.

The academic discipline underlying this work is rhetoric and composition, which studies writing as a situated practice shaped by audience, purpose, genre, and context. The language and power topic explores how writing conventions — including this vault’s — encode assumptions about whose language and knowledge count.

Entries

2 items under this folder.