# Em Dash Guide > Distinguishes hyphens, en-dashes, and em-dashes with typing shortcuts, style guide conventions, and concrete BAD vs GOOD examples for technical documentation. - Skill: `paulpas/em-dash-guide` (Agent Skill) - Install (CLI): `npx skillmds@latest add paulpas/em-dash-guide` - Raw SKILL.md: https://api.skillmd.com/api/skills/paulpas/em-dash-guide/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Docs & Writing - License: MIT - Author: paulpas (https://skillmd.com/u/paulpas) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/paulpas/em-dash-guide --- # Dash Typography Guide for Technical Documentation Selects the correct dash character (hyphen `-`, en-dash `–`, em-dash `—`) based on context and applies style guide conventions consistently across all written content. Misusing dashes is one of the most common typography errors in technical writing — it signals carelessness to readers and makes documentation harder to parse visually. ## TL;DR Checklist - [ ] Use hyphen `-` for compound modifiers (open-source project, well-tested library) - [ ] Use en-dash `–` for ranges (2024–2026, pages 15–30, A–Z index) and connections (React–Vue comparison) - [ ] Use em-dash `—` for parenthetical breaks, appositives, or attribution with no spaces on either side - [ ] Use spaced em-dashes only when following AP Style; use unspaced for Chicago/IEEE/Microsoft - [ ] Type em-dash: Ctrl+Shift+Minus (Linux), Option+Shift+= (macOS), Alt+0151 (Windows) - [ ] Never use two hyphens `--` as a substitute for an em-dash in published content --- ## When to Use Use this skill when: - Writing technical documentation, API references, or user guides that contain compound modifiers - Describing numerical ranges, dates, page numbers, or version sequences - Inserting parenthetical asides, emphatic breaks, or attribution into sentences - Reviewing or editing documentation for typography consistency - Localizing content where the target language has different dash conventions - Writing release notes, changelogs, or commit messages with version ranges (e.g., v2.0–v3.0) --- ## When NOT to Use Avoid this skill for: - Code literals and source code — use literal hyphens `-` regardless of typography rules (`npm --version`, `git log --oneline`) - URLs, file paths, or identifiers where the hyphen has structural meaning (`https://example.com/my-page`) - Email addresses or usernames with hyphenated components - When following a strict style guide that explicitly forbids em-dashes (some legal or regulatory documentation prefers commas or parentheses) --- ## Core Workflow 1. **Identify the dash function in context** — Determine what grammatical or logical role the dash serves: compound modifier, range, parenthetical break, or connection. **Checkpoint:** If the text connects two equal elements (A to B), it needs an en-dash. If it sets off a parenthetical thought, it needs an em-dash. 2. **Select the correct character** — Choose based on the function identified: - Compound modifier before a noun → hyphen `-` - Range of numbers/dates/versions → en-dash `–` - Connection between equal elements → en-dash `–` - Parenthetical aside or emphatic break → em-dash `—` - Attribution (said, wrote, explained) after a quote → em-dash `—` 3. **Apply style guide spacing rules** — Check which style guide governs the document: - Chicago Manual of Style: unspaced em-dashes (`word—word`) - IEEE/ACM/Google: unspaced em-dashes (`word—word`) - AP Stylebook: spaced em-dashes (`word — word`) - Microsoft Manual of Style: unspaced em-dashes with non-breaking spaces preferred 4. **Verify compound modifier hyphenation** — For multi-word modifiers before a noun, use hyphens to link them: - Three words → all hyphenated (`state-of-the-art implementation`) - Two words (adjective + past participle) → always hyphenate (`well-documented API`) - Two words (noun + past participle) → hyphenate if before noun (`full-grown trees`), omit after (`the trees are full grown`) 5. **Check for common substitutions** — Replace ASCII workarounds with proper Unicode characters in final published content: - `--` or `--` → em-dash `—` (in prose only, not code) - `- -` or `- `-` → em-dash `—` - Hyphen used where en-dash needed for ranges → replace with `–` --- ## Implementation Patterns / Reference Guide ### Pattern 1: Compound Modifiers (Hyphen Usage) Compound modifiers before a noun require hyphens to prevent ambiguity. Without them, readers must pause to parse the meaning. ```markdown # ❌ BAD — Ambiguous compound modifier The open source software development team uses well tested libraries. # ✅ GOOD — Hyphens clarify relationships between words The open-source software-development team uses well-tested libraries. # ❌ BAD — Reader cannot tell what modifies what She manages a small business analytics tool. # ✅ GOOD — Hyphen shows "small-business" is a compound noun acting as modifier She manages a small-business analytics tool. ``` **Rule:** When two or more words function as a single modifier before a noun, hyphenate them. Exception: do not hyphenate if the first word ends in `-ly` (e.g., `clearly defined terms` — no hyphen). ### Pattern 2: En-dash for Ranges and Connections The en-dash represents a span or relationship between two equal elements. It is wider than a hyphen but narrower than an em-dash. ```markdown # ❌ BAD — Hyphens in place of en-dashes (ambiguous ranges) The software supports versions 2.0-3.5 and the years 2024-2026. Read pages 100-150 for the complete reference. # ✅ GOOD — En-dashes clearly indicate ranges The software supports versions 2.0–3.5 and the years 2024–2026. Read pages 100–150 for the complete reference. # ❌ BAD — Using "to" or "-" for connections between equal elements The React to Vue comparison covers performance benchmarks. This guide covers Windows - macOS - Linux. # ✅ GOOD — En-dashes show equal-element relationships The React–Vue comparison covers performance benchmarks. This guide covers Windows–macOS–Linux. ``` **Key en-dash patterns:** - Numeric ranges: `0–100`, `2024–2026`, `$50–$75` - Version ranges: `v2.0–v3.0`, `Node 18–20` - Date ranges: `Monday–Friday`, `January–March` - Equal-element connections: `producer–consumer pattern`, `client–server architecture` ### Pattern 3: Em-dash for Parenthetical Breaks and Attribution The em-dash sets off a parenthetical thought more emphatically than commas or parentheses. It creates a dramatic pause that draws attention to the enclosed material. ```python # Example of em-dash usage in technical documentation prose: """ The configuration file — located at /etc/app/config.yaml — must be updated before deployment. Note two key behaviors: the application reads this file at startup; it does not hot-reload when the file changes. This is a deliberate design choice, not an oversight. The lead architect explained — in the Q3 architecture review — that this constraint stems from the underlying event loop implementation. See Section 4.2 for details. """ # ❌ BAD — Hyphen used as em-dash (ASCII substitution) The config file - located at /etc/app/config.yaml - must be updated before deployment. # ✅ GOOD — Proper em-dash with tight spacing (Chicago/IEEE style) The config file—located at /etc/app/config.yaml—must be updated before deployment. # ✅ GOOD — Spaced em-dash (AP Style convention) The config file — located at /etc/app/config.yaml — must be updated before deployment. ``` **Em-dash spacing by style guide:** | Style Guide | Spacing | Example | |---|---|---| | Chicago Manual of Style | None | `word—word` | | IEEE / ACM | None | `word—word` | | Google Developer Docs | None (em-dash preferred) | `word—word` | | Microsoft Manual of Style | Non-breaking space | `word em-dash word` | | AP Stylebook | Space on both sides | `word — word` | | Wikipedia | Spaced en-dash or spaced em-dash | `word — word` | ### Pattern 4: Keyboard Shortcuts (Typing Dashes) Each operating system provides keyboard shortcuts for inserting proper Unicode dash characters. Using these eliminates the need to copy-paste from external sources. ```markdown # Linux (GNOME, Wayland/X11) Em-dash: Ctrl+Shift+U then 2014 Enter → — En-dash: Ctrl+Shift+U then 2013 Enter → – Hyphen: - (standard key) # macOS Em-dash: Option + Shift + = (⌥⇧=) → — En-dash: Option + - (⌥-) → – Hyphen: - (standard key) # Windows 10/11 Em-dash: Alt+0151 (numpad) → — En-dash: Alt+0150 (numpad) → – Alternative: Win+. or Win+, (emoji panel), then search "dash" Alternative: MS Word auto-format (two hyphens -- become em-dash automatically) # Vim/Neovim Em-dash: Insert mode: Ctrl+V then u 2 0 1 4 Enter → — En-dash: Insert mode: Ctrl+V then u 2 0 1 3 Enter → – # VS Code (with extensions) Install "Auto Replace" or "Typographer" extension to auto-convert -- to — on space. ``` ### Pattern 5: Common Typography Mistakes and Fixes The following table covers the most frequent dash-related errors encountered in technical documentation, along with their corrections. ```markdown # Mistake 1: Using hyphens for everything (most common) ❌ BAD: Check out our open-source tools for data-science from 2020-2024. ✅ GOOD: Check out our open-source tools for data science from 2020–2024. # Mistake 2: Spaces around em-dashes without following AP Style ❌ BAD (inconsistent): The API — which uses OAuth 2.0 — supports three auth methods . ✅ GOOD (Chicago): The API—which uses OAuth 2.0—supports three auth methods. # Mistake 3: En-dash used where hyphen is needed for compound modifier ❌ BAD: This is a state – of – the – art solution. ✅ GOOD: This is a state-of-the-art solution. # Mistake 4: Missing hyphen in compound modifier creates ambiguity ❌ BAD: The manual covers self service account management features. ✅ GOOD: The manual covers self-service account management features. # Mistake 5: Using double hyphens (--) in prose instead of em-dash ❌ BAD: The --experimental-- flag enables debugging mode. ✅ GOOD: The —experimental— flag enables debugging mode. ``` --- ## Constraints ### MUST DO - Use proper Unicode dash characters in all published documentation — never ASCII substitutions (`--`, `--`) - Match em-dash spacing to the document's governing style guide (checkstyle or project convention) - Hyphenate compound modifiers before nouns; omit hyphens when the modifier follows the noun (predicate position) - Use en-dashes for all numeric ranges, version sequences, and connections between equal elements - Type dashes using platform keyboard shortcuts rather than copy-pasting from external sources ### MUST NOT DO - Never use a single hyphen `-` to represent an en-dash or em-dash in published prose - Never use two consecutive hyphens `--` as an em-dash substitute in final documentation (acceptable only in code contexts) - Do not add spaces around em-dashes unless following AP Style specifically - Do not use em-dashes for numbered list markers, bullet points, or structural formatting - Do not apply compound modifier hyphenation when the first word ends in `-ly` (e.g., `clearly defined`, `highly optimized`) --- ## Output Template When auditing or writing documentation with this skill active, produce: 1. **Dash Audit Report** — List every dash found in the reviewed text, categorized by type (hyphen/en-dash/em-dash) and context 2. **Correction Suggestions** — For each incorrect dash usage, show the original text, the correction, and the rule applied 3. **Style Guide Compliance Note** — State which style guide's spacing convention is being used for em-dashes in the reviewed document 4. **Keyboard Shortcut Reference** — Include platform-appropriate typing shortcuts for the reviewer's environment --- ## Live References > Authoritative documentation links for typography and dash usage conventions. - [Chicago Manual of Style — Punctuation](https://www.chicagomanualofstyle.org/tools_citationguide/citation_guide_2.html) - [Microsoft Manual of Style — Dash Usage](https://learn.microsoft.com/en-us/style-guide/punctuation/dashes-marks/) - [Google Developer Documentation Style Guide — Dashes](https://developers.google.com/style/dashes) - [AP Stylebook — Dash Guidance](https://www.apstylebook.com/) - [Wikipedia Manual of Style — Punctuation / Dashes](https://en.wikipedia.org/wiki/Wikipedia:Manual_of_Style/Punctuation#Dashes) --- ## Related Skills | Skill | Purpose | |---|---| | `technical-documentation` | Broader documentation patterns and structure guidance | | `style-guide` | General technical writing style conventions beyond dashes |