Revision control
Copy as Markdown
---
name: skill-language-style
description: 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).
metadata:
version: "4.0"
---
# 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 |
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).