# Skill Language Style

> Language, grammar, and style guidelines for Qt documentation including active voice, terminology, QUIP 25 standards, and proper API documentation patterns. Covers both WHAT to write (style/content) and HOW to write it (QDoc syntax).

- Skill: `qt/skill-language-style` (Agent Skill, multi-file: 12 files)
- Install (CLI): `npx skillmds@latest add qt/skill-language-style`
- Raw SKILL.md: https://api.skillmd.com/api/skills/qt/skill-language-style/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: qt (https://skillmd.com/u/qt)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/qt/skill-language-style

---


# Qt Language and Style Guidelines

**Version**: 4.0
**Purpose**: Reference for language, grammar, and style standards when writing or reviewing Qt documentation
**Scope**: Applies to all Qt documentation (QDoc comments, user guides, tutorials, API docs, examples)

---

## Overview

Language and style guidelines for Qt documentation, consolidating rules from
Qt Writing Guidelines (S1), QUIP 25 (S2), C++/QML Documentation Style
(S3/S4), and Microsoft Style Guide (S9). QDoc Manual (S10) covers command
syntax.

**Source precedence:** S1 > S2 > S3/S4 > S5/S6 > S9 (supplementary only).
**Full source details:** See `references/sources.md`.

---

## Verification Workflow (Generic)

When reviewing documentation and encountering questions about correctness
(terminology, style, patterns, syntax), follow this workflow:

### Step 1: Identify the Domain and Relevant Source(s)

| Question Type | Authoritative Source(s) |
|---------------|------------------------|
| Terminology (Qt product/module names) | S7 (Qt Terms and Concepts) |
| Language, grammar, style | S2 (QUIP 25), S1 (Qt Writing Guidelines) |
| C++ API documentation patterns | S3 (C++ Documentation Style) |
| QML API documentation patterns | S4 (QML Documentation Style) |
| Example documentation | S5 (Qt Examples Guidelines), S6 (Writing Examples) |
| Alt text | S8 (Qt Alt Text Style) |
| QDoc command syntax | S10 (QDoc Manual) |
| General style (when Qt silent) | S9 (Microsoft Style Guide) |

### Step 2: Check the Authoritative Source(s)

1. **Fetch the relevant source** (URL or local file)
2. **Record what the source says** - this is the official guidance
3. **Note if the source is silent** - may need secondary sources

### Step 3: Check Existing Documentation for Consistency

1. **Search existing docs**: `grep -r "TERM" */doc --include="*.qdoc"`
2. **Count instances** of each variant
3. **Note inconsistencies**:
   - Existing docs may conflict with authoritative source
   - Existing docs may be inconsistent with themselves
   - Some patterns may be module-specific

### Step 4: Report Both and Let Author Decide

**Output format:**
```
**[Topic]: "[Variant A]" vs "[Variant B]"**

Official ([Source]): [What the authoritative source says]

Existing usage:
- "[Variant A]": N instances (file1.qdoc, file2.qdoc...)
- "[Variant B]": M instances (file3.qdoc, file4.qdoc...)

Inconsistency: [Describe if existing docs conflict with official or themselves]

Decision for author: [Options - align with official, maintain local pattern,
or flag for broader cleanup]
```

**Why this workflow matters:**
- Authoritative sources define correctness
- Existing docs show current state (may have accumulated inconsistencies)
- Authors need full information to make informed decisions
- Some inconsistencies may warrant separate cleanup patches
- Reviewers should inform, not unilaterally enforce

---

## Rule and Source Enumeration

This skill contains **65 enumerated rules (R1-R64, R51b)** and **10 enumerated sources (S1-S10)** for easy reference.

### Rules by Category
- **Core Principles**: R1-R10 (10 rules)
- **Grammar Rules**: R11-R13 (3 rules)
- **API Documentation**: R14-R19 (6 rules)
- **Example Documentation**: R20-R23 (4 rules)
- **Alt Text**: R24-R27 (4 rules)
- **Writing Contexts**: R28-R29, R28b (3 rules)
- **Common Mistakes**: R30-R37 (8 rules)
- **Common Substitutions**: R38 (1 rule)
- **QDoc Formatting**: R39-R41 (3 rules)
- **UI and Tools Documentation**: R42-R44 (3 rules)
- **Linking Style and Syntax**: R45-R51, R51b (8 rules)
- **Structured Content**: R52-R56 (5 rules)
- **Exceptions**: R57 (1 rule)
- **Page Templates**: R58-R59 (2 rules)
- **Module Review**: R60-R62 (3 rules)
- **Admonition and Markup**: R63-R64 (2 rules)

### Sources by Authority
- **Tier 1 Qt Official**: S1-S8 (highest precedence)
- **Tier 2 Supplementary**: S9
- **Tool Reference**: S10 (syntax only)

See "Sources and Further Reading" section for complete source details.

---


## Rule router (progressive disclosure)

Core principles (R1-R10), Common Mistakes, and R38 substitutions are inline
below. The remaining rule bodies live in `references/` and are loaded on demand
at the gate that needs them. Cite rules by number; resolve the number here:

| Rules | Reference file |
|-------|----------------|
| R11-R13 (grammar), R28-R29 (contexts) | `references/prose-rules.md` |
| R14-R19 (API docs) | `references/api-docs.md` |
| R20-R27 (examples, alt text) | `references/examples-alttext.md` |
| R39-R41, R63-R64 (QDoc formatting, markup) | `references/qdoc-formatting.md` |
| R42-R44 (UI/tools) | `references/ui-tools.md` |
| R45-R51b (linking) | `references/linking.md` |
| R52-R57 (structured content: lists, tables) | `references/structured-content.md` |
| R58-R62 (page templates, module review) | `references/page-templates.md` |

When a review touches a domain above, READ the matching reference file before
applying those rules. R12 (capitalization) and R24-R27 (alt text) are the
most-missed — always load their reference file if the page has \section
titles or images.

## Core Principles

**Note**: Rules R1-R13 summarize guidelines from S1 (Qt Writing Guidelines) and S2
(QUIP 25). For full details, consult the authoritative sources directly.

### R1. Use Active Voice

Active voice over passive. See **S1, S2** for details.
- ❌ "Events will be ignored by the item" → ✅ "The item ignores events"

### R2. Be Clear and Concise

Simple, direct language. ≤20 words per sentence. See **S2** for details.
- ❌ "In order to enable" → ✅ "To enable"

**SCAN trigger:** Flag informal phrases (a lot of, kind of, sort of,
pretty much), filler words (indeed, actually, basically, essentially,
just-as-filler), and wordy constructions (causes X to occur → causes X,
a frequent requirement is to → you often need to).

---

### R3. Use Correct Terminology

**Rule**: Use Qt's standard terminology consistently. Don't invent new terms
or use incorrect class names.

**Verification**: Follow the generic **Verification Workflow** (see above).
For terminology questions, the authoritative source is **S7 (Qt Terms and
Concepts)**. The tables below are EXAMPLES, not exhaustive - always verify
against S7 for terms not listed.

**Qt Terminology Guidelines**:

| Concept | Correct Term | Incorrect Terms |
|---------|-------------|-----------------|
| User interface widget | widget | control, component |
| QML type | type | component, object, widget |
| Property value | property | attribute, field, member |
| Signal/slot mechanism | signal, slot | event, callback, handler |
| Item in QML scene graph | item | object, component, widget |
| Qt Quick Controls element | control | widget, component |
| Person writing code | developer | programmer |

**Generic UI Terminology** (for user-facing descriptions):

| Generic Term | Qt Class | Usage |
|--------------|----------|-------|
| button | QPushButton, Button (QML) | Use "button" in user docs |
| list view | QListView, ListView (QML) | Use "list view" in user docs |
| text field | QLineEdit, TextField (QML) | Use "text field" in user docs |
| dialog | QDialog, Dialog (QML) | Use "dialog" in user docs |
| toolbar | QToolBar | Use "toolbar" in user docs |
| menu bar | QMenuBar | Use "menu bar" in user docs |

**When to use which**:
- **API documentation**: Use exact class names (QListView, ListView)
- **User guides/tutorials**: Use generic terms (list view, text field)
- **Alt text**: Use generic terms, lowercase (button, dialog)
- **Code examples**: Use class names (QListView, QPushButton)

**Qt Version Numbers** (CRITICAL - commonly missed):

| Correct | Incorrect | Notes |
|---------|-----------|-------|
| Qt 5 | Qt5 | Space required before version number |
| Qt 6 | Qt6 | Space required before version number |
| Qt 5-based | Qt5-based | Space before version in compounds |
| Qt 6.5 | Qt6.5 | Space required |

**Qt Product and Module Names** (from S7 - https://wiki.qt.io/Qt_Terms_and_Concepts):

Always use official capitalization and spelling for Qt products and modules:

| Correct | Incorrect | Notes |
|---------|-----------|-------|
| Qt GUI | Qt Gui, Qt gui | Acronym must be all caps |
| Qt Core | Qt core | Module names are capitalized |
| Qt Network | Qt network | |
| Qt Qml | Qt QML (in module name) | Module is "Qt Qml", language is "QML" |
| Qt Quick | Qt quick, QtQuick (in prose) | Two words in prose |
| Qt Widgets | Qt widgets | |
| Qt Add-Ons | Qt Addon, Qt Addons, Qt Add-on Modules | Hyphenated, capitalized |
| Qt D-Bus | Qt DBus, Qt DBUS | Hyphenated |
| Qt SQL | Qt Sql, Qt sql | Acronym must be all caps |
| Qt SVG | Qt Svg, Qt svg | Acronym must be all caps |
| Qt NFC | Qt Nfc | Acronym must be all caps |
| Qt PDF | Qt Pdf | Acronym must be all caps |
| Qt XML | Qt Xml | Acronym must be all caps |
| Qt Creator | Qt creator, QtCreator | Two words, capitalized |
| Qt Design Studio | Qt design studio | Each word capitalized |
| QDoc | Qdoc, qdoc | CamelCase |

**Compound Words** (Qt documentation conventions):

| Correct | Incorrect | Notes |
|---------|-----------|-------|
| framerate | frame rate | Single word in technical contexts |
| runtime | run time, run-time | Single word as noun/adjective |
| filename | file name | Single word |
| namespace | name space | Single word |
| checkbox | check box | Single word |
| toolchain | tool chain | Single word |
| codebase | code base | Single word |
| standalone | stand-alone | Single word |

**Qt-Specific Spellings (API-driven)** — *Qt-only reference; seed list, expand
as decisions are confirmed*:

For terms where general or external style guides disagree or are split, Qt's
spelling follows its **API identifiers** and dominant in-house usage. These
take precedence over external sources (e.g., S9 Microsoft Style Guide) when
they conflict. Verify the API identifier before adding an entry.

| Correct (Qt) | Avoid | Why |
|--------------|-------|-----|
| antialiasing | anti-aliasing | Matches the API: `QPainter::Antialiasing` (render hint) and the QML `Item.antialiasing` property. ~85–100% of Qt docs use one word (incl. "multisample antialiasing"). Industry/3D-API usage is split — formal specs and acronym expansions (MSAA = Multisample Anti-Aliasing, FXAA, TAA) often hyphenate — but Qt's API decides. Exception: a branded, proper-noun acronym expansion (e.g., NVIDIA "Fast Approximate Anti-Aliasing") may keep its own hyphenation. |

**Sources**: S2 (QUIP 25), S1 (Qt Writing Guidelines), S7 (Qt Terms and Concepts)

**IMPORTANT - Authoritative Source Verification**:

The tables above are NOT exhaustive. When reviewing terminology:

1. **Scan for Qt patterns**: `Qt[0-9]`, `Qt [A-Z]`, product names, module names
2. **Verify against S7**: Fetch https://wiki.qt.io/Qt_Terms_and_Concepts for authoritative definitions
3. **When in doubt, check source**: Do not assume a term is correct just because it's not in the tables above

**Common patterns to scan for**:
- `Qt[0-9]` → Should be `Qt [0-9]` (space required)
- `QtQuick` in prose → Should be `Qt Quick` (two words)
- `QtCreator` → Should be `Qt Creator` (two words)

---

### R4. Use Present Tense

Present tense for current behavior. See **S2** for details.
- ❌ "will return" → ✅ "returns"

**SCAN trigger:** Search for "will" + verb (will copy, will happen, will
make, will show, will throw). Flag unless conditional future ("if X, Y
will occur") or planned deprecation ("will be removed in Qt 7").

### R5. Use Imperative Mood for Instructions

Imperative for briefs/instructions, indicative for descriptions. See **S3, S4**.
- Imperative: "Returns the value." / "Call this function..."
- Indicative: "This property holds..."

### R6. Use "You" for User Instructions

Address users with "you" in guides/tutorials. See **S1, S2** for details.
- ❌ "One can configure..." → ✅ "You can configure..."
- API docs: Use imperative/indicative patterns (R14-R19) instead

### R7. Avoid Jargon and Idioms

Write for international audience. No idioms. See **S1, S2** for details.

**SCAN trigger:** Flag common English idioms (double-edged sword, behind
the scenes, under the hood, out of the box, on the fly, from scratch).
Replace with literal equivalents. Also: "like" (introducing examples) →
"such as".

### R8. Be Consistent

Same word for same concept throughout. See **S2** for details.

### R9. Use Parallel Structure

Same grammatical structure in lists. See **S2** for details.
- ❌ "Set... / Calling... / You should..." → ✅ "Set... / Call... / Verify..."

---

### R10. Avoid Ambiguous Pronouns

Clear pronoun references. When in doubt, repeat the noun. See **S2** for details.
- ❌ "It is updated first" → ✅ "The item is updated first"

---


## Common Mistakes (Quick Reference)

See rules R1-R38 for details:
- R30: Passive voice → Use active
- R31: Future tense → Use present
- R32: Wordy phrases → Be concise
- R33: Ambiguous "this" → Be specific
- R34: Inconsistent terms → Pick one
- R35: Missing \brief on class/type/property → Add \brief (see R14 for scope)
- R36: No period in brief → Add period
- R37: "Neutral voice" → Use "imperative/indicative mood"

---


## R38. Common Substitutions

Avoid Latin terms, formal/verbose phrases, and hedging words. See **S1, S2, S9**
for complete lists.

**Key substitutions** (most commonly flagged):
| Avoid | Use |
|-------|-----|
| e.g., i.e., etc., via | for example, that is, (be specific), through |
| in order to | to |
| utilize | use |
| simply, obviously, clearly | (omit) |
| since/as (causation) | because |

**Full substitution lists**: Consult S2 (QUIP 25) and S9 (Microsoft Style Guide).

---


## Fix Verification (MANDATORY)

**CRITICAL: Every language fix must be verified against ALL rules before presenting.**

### The Problem

Language fixes often address one issue while introducing another:

| Fix addresses... | But introduces... |
|------------------|-------------------|
| R1 (passive voice) | R2 (wordiness) |
| R2 (wordiness) | R1 (passive voice) |
| R38 (Latin term) | R10 (missing article) |
| Grammar error | R40 (line too long) |

### Verification Process

**Before presenting ANY language suggestion:**

1. **Draft the fix**
2. **Re-read the ENTIRE corrected sentence** - not just the changed part
3. **Check against ALL language rules** (see checklist below)
4. **If fix introduces new issues, revise** - iterate until fully compliant
5. **Only present the final, fully-compliant suggestion**

### Quick Verification Checklist

For every drafted fix, verify:

```
- [ ] R1: Active voice? (no "is/are/was/were [verb]ed", "can be [verb]ed")
- [ ] R2: Concise? (no "in order to", "some of the", "provide a way to")
- [ ] R4: Present tense? (no "will return", "will be")
- [ ] R10: Correct articles? ("the", "a", "an" where needed)
- [ ] R38: No Latin? (no "via", "e.g.", "i.e.", "etc.")
- [ ] R40: ≤80 columns?
- [ ] Grammar correct? (agreement, possessives, parallelism)
- [ ] Clear and readable?
```

### Domain Terms Exception

**Before flagging terminology, verify it's not a valid technical term:**

- **C++ terms**: "in-place" (construction), "move semantics", "RAII", "emplace"
- **Qt terms**: Check Qt Terms and Concepts (S7)
- **QML terms**: Check QML Documentation Style (S4)

**Example**: "inplace" or "in-place" is valid C++ terminology. Do NOT flag as spelling error.

### Example - Iterative Verification

```
Original: "The data can be also assigned directly via the property"

Draft 1: "The data can also be assigned directly via the property"
  ✗ R1: Still passive ("can be assigned")
  ✗ R38: Latin term ("via")
  → REVISE

Draft 2: "You can also assign the data directly via the property"
  ✓ R1: Active ("You can assign")
  ✗ R38: Latin term ("via")
  → REVISE

Draft 3: "You can also assign the data directly through the property"
  ✓ R1: Active
  ✓ R38: No Latin
  ✓ R2: Concise
  ✓ R40: 58 chars
  → PRESENT
```

---


## Sources

See `references/sources.md` for the authoritative source list (S1-S10).