em-dash-guide

name: em-dash-guide description: Distinguishes hyphens, en-dashes, and em-dashes with typing shortcuts, style guide conventions, and concrete BAD vs GOOD examples for technical documentation. license: MIT compatibility: opencode metadata: version: "1.0.0" domain: writing triggers: em dash, en dash, hyphen, dash typography, how do i type dashes, long dash, range notation, compound modifier dash archetypes:

• educational anti_triggers:
• brainstorming
• vague ideation response_profile: verbosity: medium directive_strength: low abstraction_level: strategic role: reference scope: implementation output-format: report content-types:
• guidance
• examples
• do-dont related-skills: technical-documentation, style-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.

# ❌ 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.

# ❌ 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.

# 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:

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.

# 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.

# 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
• Microsoft Manual of Style — Dash Usage
• Google Developer Documentation Style Guide — Dashes
• AP Stylebook — Dash Guidance
• Wikipedia Manual of Style — Punctuation / Dashes

Related Skills