Technical Writing

This deck introduces the foundations of technical writing, covering the principles behind clear, useful, and well-structured documentation. You'll explore ideas like understanding your audience, starting from user needs, choosing the right type of writing (procedural, conceptual, or reference), and using examples, headings, and visuals to guide readers. It also touches on plain language, controlling jargon, and making assumptions explicit so that your documents are accessible to the people who actually rely on them.

It's a great starting point if you're new to technical writing, a student learning the craft, or a professional such as a developer, engineer, or analyst who wants to communicate more clearly through documentation. Even if you already write technical content occasionally, the deck offers a useful refresher on the reasoning behind common best practices, helping you think more intentionally about how you structure and present information.

To get the most out of your study sessions, try spacing your reviews over several days rather than cramming everything at once, since the concepts build on each other. After working through a few cards, pause and think of a real document you've written or read recently, then apply the idea you just learned to it. Connecting each principle to something concrete will make the knowledge stick and show you right away where your own writing could improve.

Technical writing is the craft of explaining complex information so clearly that readers can understand and act on it without needing the author present. The work pays off by reducing confusion, improving adoption of products and processes, and letting knowledge scale beyond live conversations. Every document is written for a specific audience, the actual reader the writer is trying to help, persuade, or guide, rather than a generic "user." Because of that, clear technical writing always starts from the reader's real need and answers the question they arrived with, instead of showcasing everything the author happens to know.

Clarity in this craft comes from being specific, well structured, concise, and easy to scan. Plain language is the usual vehicle: familiar words, direct sentences, and clean structure that do not sacrifice accuracy. Tone and voice shape how the document feels. A direct, helpful, neutral, and sometimes warm voice builds trust across pages, while second-person address ("you" rather than "the user" or "one") shortens sentences and reads more like a guide than a manual. Imperative mood carries procedural steps cleanly, simple present describes current behavior, and simple past reports completed actions, while passive voice tends to hide the actor and break the imperative pattern readers expect. Inclusive language widens the audience, and consistency in terminology, capitalization, and formatting ties the site together.

Style decisions are usually codified in a style guide so that a docs team does not re-debate them on every page. Public style guides such as the Google Developer Documentation Style Guide and the Microsoft Writing Style Guide are common baselines that teams adapt, capturing word choice, formatting, voice, and inclusive-language rules in one place. A useful self-check while writing is the question, "What does this reader need to know, do, or decide immediately after reading this section?" When the answer is obvious and the prose is short, the foundation is solid.

Strong documents move the reader from context to steps to examples to troubleshooting in a logical order, and the way the page is shaped matters as much as the words on it. Headings are the spine: they help readers find the right section quickly, communicate the content hierarchy, and act as the table of contents that scanners rely on. Headings should descend without skipping levels, with one H1, H2s for top sections, and H3s inside H2s, so navigation and screen readers stay honest. Titles should start with a noun or verb ("Configure SSO," "Authentication overview") rather than an article, because they sort and read more cleanly. The first sentence after the title, often called a landing sentence, should preview what the page accomplishes so scanners can confirm they are in the right place.

Different kinds of writing call for different shapes. Procedural writing gives step-by-step instructions for a task and works best in the imperative mood, with each step short, numbered when order matters, and parallel so items read as peers. Conceptual writing explains how something works or why it matters before asking the reader to act. An effective summary sentence tells the reader what the section will help them accomplish, while each paragraph should advance a single idea so a reader who skips a paragraph never misses a separate point buried inside it. Short paragraphs, action-oriented headings, and progressive disclosure that reveals the simplest useful guidance first, then deeper detail only when needed, all support the way most readers actually consume technical content. The F-shape reading pattern, in which eyes sweep horizontally across the top and then in shorter sweeps lower down, is fed by headings, lists, and bold cues that match the way readers scan.

Several reusable patterns show up across strong docs. The inverted pyramid puts the most important conclusion or instruction first, then expands with context and ends with background or edge cases, and it works at the page level and inside a single paragraph. Scannability is not a stylistic flourish; most readers scan before reading deeply, especially when troubleshooting under time pressure. Callouts (note, tip, warning, danger) highlight information that would be dangerous to miss, with warnings reserved for actions that can cause data loss, security holes, or irreversible damage and notes for useful context that is helpful but not dangerous. Prerequisites sections tell the reader exactly what they must already have, know, or configure before the instructions will work. A TL;DR at the top of a long page, an overview that sets context, a topic sentence at the head of each paragraph, a colon introducing a list or code example that elaborates on the preceding clause, and a troubleshooting section that anticipates common failures all reduce the cognitive load of getting to the right answer quickly.

Examples turn abstractions into concrete cases that readers can copy, compare, or adapt, and they earn trust only when they actually run. A useful example is the shortest one that still demonstrates the documented behavior, with no unrelated features, decorative configuration, or copy-paste noise, and it should be tested in a fresh environment so the reader sees the documented result. Commands and snippets must be copy-pasteable, because trivial edits, placeholder names, or missing flags break trust quickly. "Show, don't tell" pays off especially for APIs and CLIs, where a real input and its output are more convincing than any amount of prose, and showing expected output also lets readers verify their own run, diagnose typos, and trust that the documented behavior matches reality.

Code blocks present runnable or copy-pasteable commands, configuration, or output with preserved whitespace and no prose wrapping around the syntax. Placeholder code that uses names like "my-host" or "TODO" is dangerous when the placeholders are not flagged, because a hurried reader will paste it literally; clearly marking placeholders keeps examples honest. Type signatures document the shape of a function while prose documents the meaning, and most well-documented code needs both. In Python and similar languages, a docstring is the literal string placed at the top of a function, class, or module to document purpose, arguments, return value, and exceptions, and it sits alongside the code rather than replacing it. Self-documenting code uses clear names and small functions to reduce the need for prose, but it is never enough on its own: intent, context, and trade-offs still need writing, and the most valuable kind of code comment is the "WHY" comment that explains the reasoning behind a non-obvious line, such as why a particular retry count was chosen over another.

Visuals clarify structure or sequence when text alone would be slower to understand, but they should earn their place. Screenshots are the right choice when the visual is the answer, such as locating a UI control or reading a diagram, and a reader would otherwise have to reconstruct the picture mentally from prose; they are the wrong choice for things code blocks or short text could say better, because screenshots are expensive to maintain and break the moment the UI changes. Diagrams model relationships or flow, with sequence diagrams for ordered messages between components and flowcharts for decision branches in processes like runbooks and troubleshooting trees. ASCII art is acceptable in code comments, READMEs, and terminal contexts where rendered images are not an option, when simplicity is the goal. Tables align parallel facts across rows so readers can scan a single column, while prose is better for sequential or causal relationships, single-row cases, or cells that would become paragraphs; a definition list is a lighter alternative for term-and-definition pairs like configuration keys. Every image needs alt text that describes what the image conveys rather than how it looks, and purely decorative images should have empty alt text. On mobile, long paragraphs, wide tables, and side-by-side code blocks break easily, so writing for narrow screens first and treating wide layouts as a progressive enhancement keeps docs usable everywhere.

Different reader goals call for different document types, and recognizing which one to write is half the work. A tutorial is a guided learning experience that takes a beginner through a sequence to build the mental model. A how-to guide is a recipe aimed at an informed reader who already has the mental model and just needs a specific goal reached. Reference documentation exhaustively lists endpoints, parameters, fields, and error codes in a lookup-oriented format with little narrative, and the most important and most-frequently-used fields are ordered first so readers can find the answer faster. FAQs answer anticipated, generic questions and are not a substitute for proper how-tos on complex tasks, while troubleshooting sections diagnose specific symptoms with concrete next steps and are procedural rather than informational. A troubleshooting tree maps symptoms to actions without prose walls: if you see X, check Y; if Y is true, do Z; if not, check W. An error code reference lists every error the system can return, with a unique identifier, plain-language meaning, common causes, and remediation steps.

Operational writing has its own patterns. A runbook gives on-call responders exact steps to diagnose, mitigate, and resolve a specific production issue. A postmortem is a written record of an incident covering timeline, root cause, contributing factors, customer impact, and concrete action items to prevent recurrence, written in a blameless frame so attention stays on systems, signals, and decisions under uncertainty rather than on individual scapegoats. A design doc explains a proposed technical change with a problem statement, goals and non-goals, the chosen solution, alternatives considered, trade-offs, risks, rollout plan, and open questions. An RFC is broader, written for an engineering audience to debate direction, while a design doc is more concrete and aimed at reviewers who will approve implementation. An Architecture Decision Record, or ADR, captures one significant decision, the context, the choice, the consequences, and the alternatives rejected, signed by date and author; recording the rejected alternatives prevents the same debate from restarting whenever a new joiner questions the choice.

A README answers five questions fast: what this is, who it is for, how to install, how to run, and where to learn more, with anything else pushed into linked docs. A CHANGELOG entry is a per-version note that lists user-visible changes under Added, Changed, Fixed, Removed, and Security, so users can see what to expect on upgrade, and SemVer's MAJOR.MINOR.PATCH scheme interacts with docs by pinning references to a major version while guides target the latest minor. API documentation is the human- and machine-readable description of an API, including endpoints, request and response shapes, error codes, authentication, rate limits, and examples, often expressed in OpenAPI and rendered into interactive reference. Deprecation notices must state the removal version, explain the migration path, and link to the replacement, because telling users something is going away without telling them how to move creates churn and support tickets. Feature flag documentation should describe the flag, its default, and which audiences currently see the feature, while known-issue sections list active bugs or limitations with workarounds, affected versions, and a link to tracking. Edge cases, error conditions, limits, and boundary behaviors belong in reference or troubleshooting rather than in tutorials, because the happy path and the unhappy path both deserve coverage.

Information architecture is the structure of categories, sections, and pages that determines how readers find content, and good IA matches the reader's tasks rather than the org chart. A card-sort exercise, where readers group proposed doc topics into categories, is a useful way to validate navigation labels and section boundaries before committing to them. The typical order of doc types on a product site starts with a tutorial or quickstart, then concepts, then how-to guides, then reference, mirroring the journey of a learning reader. A landing page for a product area explains what the area is for, lists the most common tasks, and links into tutorials and reference. A user journey is the sequence of docs a typical reader traverses from first hearing about the product to running an advanced setup, and each step in that journey should land cleanly. A glossary that defines domain terms in one place pays off in any product with a heavy domain, because it reduces the need for inline definitions.

Navigation has to support both kinds of readers: those scanning a category and those drilled into a specific page. A two-level pattern, with a sidebar of sections and an in-page table of contents of subsections, serves both. Breadcrumbs show the path from the docs home to the current page so readers can back up without losing context, and a long page benefits from its own table of contents so mobile readers can jump directly to the section that matches their task. Some readers always search instead of browsing, so titles should match the words readers actually type, including error messages and parameter names, and a search bar lets those readers reach the answer in one or two clicks. A 404 page acknowledges the missing content, suggests where the reader might go next, and offers a search box instead of a dead end.

URLs and links deserve their own discipline. A canonical URL is the one preferred address for a page, with other addresses redirecting to it. Redirects preserve SEO and external links when content moves. Link rot, when a referenced URL changes or dies, is fought by preferring relative links, version-pinning, and showing a code snippet alongside any link. Anchor text is the visible words of a link and should be descriptive of the destination ("OAuth setup guide"), never "here," "this," or a raw URL, because link text is a key piece of information scent. A stub page is a placeholder that exists so a link does not 404 but contains only a heading and a TODO; stubs are useful in a doc plan but harmful if they ship unflagged. Mobile-first writing means long paragraphs, wide tables, and side-by-side code blocks are designed for narrow screens first, with wider layouts treated as a progressive enhancement. A doc plan is a short list of the docs to write, update, or retire for a release, mapped to features, with owners and dates, agreed before launch.

Quality in technical writing is built through structured review, not just careful first drafts. A docs review checks three things: accuracy, meaning whether the doc matches the product; completeness, meaning whether edge cases and error conditions are covered; and clarity, meaning whether a new reader would get it. The reviewers should be a mix of a technical reviewer, who is an engineer or subject-matter expert verifying that claims and examples are correct, and a copy editor, who focuses on language, grammar, style, terminology consistency, and tone. When possible, a fresh reader who is not the author should test the doc, because authors fall into the curse of knowledge and no longer notice the assumptions and ambiguity that trip beginners up. The opposite trap is the "dumb it down" reflex: clarity is not the same as oversimplification, and important nuances, constraints, and edge cases must be preserved. Precision also matters separately from accuracy, since a precise but inaccurate number is worse than a rounded accurate one.

The most important quality check for examples is a smoke test: running the example exactly as written, in a fresh environment, and confirming that the documented output appears. Examples that fail the smoke test should not ship, because broken examples erode trust in the rest of the document. The golden path is the shortest, most-supported route through the product to a useful result, and docs should make that path obvious and well-paved. Edge cases, including non-default inputs, error conditions, limits, and boundary behaviors, are usually covered in reference or troubleshooting rather than in tutorials, but they must be covered somewhere, because the happy path and the unhappy path both deserve documentation.

Maintenance is the ongoing work of updating content as products, APIs, and workflows change, and stale docs are a product problem because they create support load and lead users into avoidable mistakes. The single source of truth principle says that information should live in exactly one place, with other pages linking to it rather than copying it, so updates propagate automatically and the docs never contradict each other. Duplicate content is the failure mode of that principle, and once two copies drift apart, a reader following the wrong copy wastes time or hits bugs. A useful habit for maintenance-friendly writing is to prefer clear structure and reusable patterns so updates can be made quickly when the product changes. For most features, the minimum viable documentation is a short overview, a quickstart, and a reference for every public option, with other doc types added later once support feedback shows the gaps.

The docs-as-code approach stores documentation in the same repository as the product, in plain text formats like Markdown or AsciiDoc, reviewed through pull requests and built by a static site generator. The benefits fall out of that placement: docs are versioned with the product, reviewed by engineers, branched per release, searchable as text, and checkable in CI for broken links and lint rules. A static site generator such as Docusaurus, MkDocs, Sphinx, or Hugo turns those plain-text source files into HTML, navigation, and a search index. Continuous deployment of documentation means that doc changes merged to the main branch are automatically published within minutes, so users see updates as soon as engineers ship them. Because the docs ship from the same pipeline as the code, every change can be tied back to a release and a feature.

Quality tooling extends the same idea to prose. A doc lint tool such as markdownlint, Vale, or alex automatically checks style issues, banned words, broken links, and accessibility problems in CI. Vale is popular because it is syntax-aware and runs both locally and in CI, and teams ship custom rule sets to enforce their style guide, including domain terminology that public style guide baselines do not cover. A broken-link check is an automated crawl that follows every link in the docs and reports any that 404 or redirect unexpectedly, often run on every pull request. The result is that a wide range of small problems, from a stray "click here" to a dead reference, are caught before they reach readers.

Feedback and metrics close the loop. A feedback widget on each page, usually a small "Was this helpful?" prompt, lets readers flag bad pages, and aggregated feedback is a strong signal for what to rewrite first. The most important metric for procedural content is task success, the rate at which a reader with a goal completes it using the doc alone, and a common related KPI is time to first hello world, the time from opening the quickstart to seeing a working sample output. Changelogs and docs should connect so users learn not just that something changed but how the change affects the way they work, and versioning maintains a separate copy of the docs for each major release so users on older versions still see accurate guidance. The strong durable habits are simple: write for the reader's task, test every example, cut anything that does not improve understanding, write the shortest path to correct action, and keep the next right action obvious.