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)

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:

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:

Generic UI Terminology (for user-facing descriptions):

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

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:

Compound Words (Qt documentation conventions):

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.

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

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:

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