Technical Writing in Markdown: Structure & Workflow

Markdown works well for technical writing because source files are readable, diffable, searchable, and easy to render in many documentation systems. It does not replace information architecture, examples, review, or maintenance.

First choose the page's job—tutorial, how-to guide, reference, or explanation—then use the matching structure. For endpoint-specific patterns, see how to write API documentation.

Why Markdown won

Before Markdown became the default, teams wrote docs in:

• Word documents — versioned in SharePoint, unsearchable, unreadable on mobile
• Wikis (Confluence, MediaWiki) — siloed, decoupled from code, hard to back up
• Google Docs — great for drafts, terrible for anything structured or versioned
• XML/DocBook — powerful, expressive, and nobody wanted to write it

Markdown won because it's:

1. Plain text. It lives in Git. It diffs cleanly in code review. It's readable in a terminal, a text editor, or a web browser. It survives tool migrations because every tool reads plain text.
2. Lightweight. The core syntax fits on a Markdown cheat sheet and can be learned incrementally.
3. Extensible. Frontmatter for metadata, code blocks for examples, fenced languages for syntax highlighting, Mermaid for diagrams, MDX for interactive components. You can always go deeper when you need to.
4. Specified core. CommonMark defines portable fundamentals; GFM and renderer-specific extensions add tables, tasks, diagrams, components, or metadata.

The practical result: if you write docs in Markdown, you can move them between tools with almost no friction. If you write docs in a proprietary format, you're locked in.

The four Diátaxis modes

Before writing, identify the page's job. The Diátaxis framework separates four modes:

• Tutorials — learning-oriented lessons that help a beginner gain competence through a guided experience.
• How-to guides — task-oriented. "How to enable SSO." Reader has a specific problem; you give them the shortest path to a solution.
• Reference — information-oriented descriptions of machinery, such as an endpoint, command, or configuration field.
• Explanation — understanding-oriented discussion of concepts, context, alternatives, architecture, and design decisions.

Many docs fail because they try to be all four at once. A tutorial with too much reference material is boring. A reference doc with too much prose is unsearchable. Pick a type per page.

Directory structure

For a mid-sized project:

docs/
├── index.md                    # Landing page
├── getting-started/
│   ├── installation.md
│   ├── quickstart.md
│   └── first-project.md
├── guides/                     # How-to
│   ├── authentication.md
│   ├── deploying.md
│   └── migrating-from-v1.md
├── reference/
│   ├── api/
│   │   ├── users.md
│   │   └── projects.md
│   ├── cli.md
│   └── configuration.md
├── concepts/                   # Explanation
│   ├── architecture.md
│   └── data-model.md
└── assets/
    └── images/

Principles:

• Flat is better than deep. Don't nest more than two levels.
• Name files by topic, not by type. authentication.md, not guide-auth-v2.md.
• One concept per file. Long pages that cover multiple concepts are unsearchable.
• Landing pages per section. Each folder gets an index.md that orients the reader.

Writing structure

Every technical page benefits from the same skeleton:

# Page title

One-sentence summary of what this page covers and who it's for.

## Prerequisites

- What the reader must already know or have set up.

## Core content

Sections organized by task or concept, not by internal team structure.

## Troubleshooting

Common errors and their fixes.

## Related

- Links to adjacent docs.

The ## Prerequisites and ## Troubleshooting sections are the two most skippable and most valuable. Prerequisites stop readers from wasting time on content they're not ready for. Troubleshooting catches them before they open a support ticket.

Voice and style

A few rules that apply to almost all technical writing:

1. Use second person. "You create a user by..." — not "The user is created by..." or "We create a user by...". The reader is doing the work; address them directly.
2. Use present tense. "The API returns a 200." Not "The API will return a 200."
3. Use active voice. "The worker processes the job." Not "The job is processed by the worker."
4. Be concrete. Every claim should have a concrete example or a code block.
5. Short sentences. If a sentence has two commas, it probably wants to be two sentences.
6. Don't apologize. "Unfortunately, this feature requires..." — cut the "unfortunately." The reader doesn't need your feelings about the API.
7. Define acronyms on first use. Even ones you think are obvious.

Code examples

Working code examples are especially valuable in task and reference documentation. Every example should be:

• Copy-paste runnable. If the reader has to edit YOUR_API_KEY before running, say so right next to the example.
• Minimal. No imports for unused libraries. No placeholder "// your logic here" comments.
• Language-tagged. Always use fenced code blocks with a language hint for syntax highlighting.

```bash
curl -X POST https://api.example.com/v1/users \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]", "name": "Ada"}'
```

Show the response too, when it's non-obvious:

```json
{
  "id": "usr_abc123",
  "email": "[email protected]",
  "name": "Ada",
  "created_at": "2026-02-18T14:00:00Z"
}
```

Diagrams with Mermaid

Mermaid diagrams are text, which means they're Git-friendly, diffable, and easy to update. GitHub and some documentation platforms render Mermaid; others require a plugin or build step.

```mermaid
sequenceDiagram
    Client->>API: POST /login
    API->>Database: verify credentials
    Database-->>API: user record
    API-->>Client: JWT token
```

Use Mermaid for sequence diagrams, flowcharts, and state machines. For architecture diagrams with precise layout needs, a tool like Excalidraw or diagrams.net exporting to SVG is better — but keep the source file in the repo so someone can edit it later.

Frontmatter and metadata

Most static site generators use YAML frontmatter for per-page metadata:

---
title: "Authentication"
description: "How to authenticate requests to the API"
sidebar_position: 2
tags: ["auth", "security"]
---

Minimum fields: title and description. The description feeds your site's meta tags and search result snippets — write it deliberately, not as an afterthought.

Links and cross-references

• Use relative links inside the docs site: [authentication](./authentication.md). They survive URL structure changes.
• Use absolute URLs for external references: [RFC 6749](https://datatracker.ietf.org/doc/html/rfc6749).
• Prefer descriptive link text over "click here." Screen readers list links out of context.
• Check for broken links in CI. Tools: lychee, markdown-link-check. Run on every PR that touches docs.

Review workflow

The fastest way to kill a docs culture is to require three approvals for every typo fix. Lower the friction:

• Docs-only PRs don't need a full engineering review. One approval from anyone with context is enough.
• Let non-engineers edit. PMs, designers, and support engineers often spot issues engineers miss. GitHub's web editor and the "Edit on GitHub" link on rendered docs are underused features.
• Use suggestions, not full reviews, for small edits. GitHub's suggestion UI merges in one click.

For larger changes — new sections, architectural updates — use the same PR template you use for code: what changed, why, what was considered, what was rejected.

Keeping docs fresh

Docs rot. Here are the patterns that slow the rot:

• Docs in the same repo as code. Moving code to v2 means editing docs in the same PR.
• A docs owner per section. Someone's name goes in the CODEOWNERS file for each folder.
• Scheduled doc audits. Choose a quarterly, twice-yearly, or risk-based cadence and state it consistently in the ownership plan.
• "Was this helpful?" widgets. Simple thumbs-up/thumbs-down at the bottom of each page. Log to a spreadsheet. Fix the low-scoring pages first.
• Automated stale detection. Script that flags any .md file not touched in N months when the surrounding code has changed. Not gospel, but a useful nudge.

Tooling checklist

A modern Markdown docs stack:

• Editor: VS Code or Cursor with the Markdown All-in-One extension, or Obsidian for personal knowledge. See the editors comparison.
• Linter: markdownlint-cli2 in pre-commit and CI. Catches inconsistent heading levels, trailing whitespace, broken tables.
• Link checker: lychee or markdown-link-check in CI.
• Spell checker: cspell with a project-specific dictionary for product names and technical terms.
• Formatter: Prettier (handles Markdown) or mdformat. Opinion-based — pick one and enforce in pre-commit.
• Static site generator: See FAQ above. For most teams: MkDocs Material or Docusaurus.
• Analytics: Use views, search exits, feedback, support cases, and product risk together. Preserve accurate low-traffic reference pages that serve rare but important tasks.

Common mistakes

• Writing docs for yourself, not the reader. Your internal team structure, project history, and debate about the feature are irrelevant. Write what the reader needs to know.
• Dumping everything on the reader. If a page has 14 H2s, split it.
• Skipping examples. Every concept gets at least one runnable example.
• Inconsistent terminology. If it's a "project" on one page and a "workspace" on the next, pick one and do a find-and-replace.
• Stale screenshots. Replace them or remove them. An out-of-date screenshot is worse than no screenshot.

A starter template

---
title: "Feature name"
description: "One-line description of what this feature does."
---

# Feature name

This page explains how to [do the thing]. You'll need [prerequisites].

## Prerequisites

- ...

## Overview

2–3 paragraphs of context. What problem does this solve? When would you use it?

## Usage

Step-by-step with runnable examples.

## Options

Reference table of configuration options.

## Examples

Real-world use cases.

## Troubleshooting

| Error | Cause | Fix |
| ----- | ----- | --- |

## See also

- Links to adjacent docs.

Copy this into a template file in your repo. New docs start here, get edited down to what matters.

Closing

Technical writing isn't a separate skill from engineering — it's part of the job. The docs you write today are the docs someone on your team (maybe you, in six months) will read to remember why the system works the way it does.

Markdown is the default format because it strips away the ceremony. Write the words. Ship the docs. Fix them when they're wrong.