skill-language-style

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) Fetch the relevant source (URL or local file) Record what the source says - this is the official guidance Note if the source is silent - may need secondary sources Step 3: Check Existing Documentation for Consistency Search existing docs : grep -r "TERM" */doc --include="*.qdoc" Count instances of each variant 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: Scan for Qt patterns : Qt[0-9] , Qt [A-Z] , product names, module names Verify against S7 : Fetch https://wiki.qt.io/Qt_Terms_and_Concepts for authoritative definitions 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.