Qt Documentation Style Rules Quick Reference

This page provides a consolidated reference of language and style rules for Qt documentation, with citations to their authoritative sources. Use this as a checklist when writing or reviewing Qt documentation.

Note: These rules are prescriptive for new and updated documentation. Existing Qt documentation may not fully comply with all rules.

Sources

The following official sources define Qt documentation standards. When sources conflict, follow the hierarchy: S1 → S2 → S3/S4 → S9.

ID	Source	URL	Purpose
S1	Qt Writing Guidelines	https://wiki.qt.io/Qt_Writing_Guidelines	Primary coordination document for all Qt documentation standards
S2	QUIP 25 - Documentation Writing Style	https://code.qt.io/cgit/meta/quips.git/plain/quip-0025-Documentation-Writing-Style.rst	Language, grammar, word choice, and formatting standards
S3	C++ Documentation Style	https://wiki.qt.io/C%2B%2B_Documentation_Style	Patterns and requirements for C++ API documentation
S4	QML Documentation Style	https://wiki.qt.io/QML_Documentation_Style	Patterns and requirements for QML API documentation
S5	Qt Examples Guidelines	https://wiki.qt.io/Qt_Examples_Guidelines	Code quality, screenshots, and build requirements for examples
S6	Writing Example Documentation and Tutorials	https://wiki.qt.io/Writing_Example_Documentation_and_Tutorials	11 mandatory elements and tutorial structure
S7	Qt Terms and Concepts	https://wiki.qt.io/Qt_Terms_and_Concepts	Official Qt terminology and product naming conventions
S8	QDoc Style Guidelines	https://wiki.qt.io/QDoc_Style_Guidelines	QDoc command formatting and alt text rules
S9	Microsoft Writing Style Guide	https://learn.microsoft.com/en-us/style-guide/welcome/	Supplementary reference when Qt sources don't specify
S10	QDoc Manual	https://doc.qt.io/qt-6/qdoc-index.html	QDoc command syntax (not a style authority)

API Documentation Requirements

Requirements for documenting C++ and QML APIs are defined in the official style guides:

C++ APIs: See C++ Documentation Style for class, function, property, and signal documentation requirements
QML APIs: See QML Documentation Style for QML type, property, method, and signal documentation requirements
Examples: See Writing Example Documentation and Tutorials for the 11 mandatory elements

Key points:

Classes and QML types require
```
\brief
```
,
```
\since
```
, and
```
\inmodule
```
/
```
\inqmlmodule
```
Properties require
```
\brief
```
Functions and methods should start with an action verb ("Returns...", "Sets...")

Core Principles (R1-R10)

These fundamental writing principles apply to all Qt documentation. They ensure clarity, consistency, and accessibility for an international audience. Derived primarily from QUIP 25 (S2), Qt Writing Guidelines (S1), and Microsoft Writing Style Guide (S9).

Rule	Summary	Sources	Notes
R1	Use active voice	QUIP 25, Qt Writing Guidelines, MS Style Guide	Passive acceptable when actor unknown. "The item ignores events" not "Events are ignored by the item"
R2	Be clear and concise	QUIP 25, MS Style Guide	Aim for ≤20 words per sentence. "To" not "In order to"
R3	Use correct terminology	QUIP 25, Qt Writing Guidelines, Qt Terms and Concepts	Use "widget" not "control", "type" not "component", "developer" not "programmer"
R4	Use present tense	QUIP 25, Qt Writing Guidelines, MS Style Guide	"Returns true" not "Will return true"
R5	Use imperative mood for instructions	MS Style Guide, C++ Doc Style, QML Doc Style	Briefs: "Returns the value." Descriptions: "This property holds..."
R6	Use "you" for user instructions	QUIP 25, Qt Writing Guidelines, MS Style Guide	In guides/tutorials and tools docs. Not in API reference docs.
R7	Avoid jargon and Latin terms	QUIP 25, Qt Writing Guidelines, MS Style Guide	"for example" not "e.g.", "that is" not "i.e.", "through" not "via"
R8	Be consistent	MS Style Guide	Same word for same concept throughout
R9	Use parallel structure	MS Style Guide	List items use same grammatical form
R10	Avoid ambiguous pronouns	QUIP 25, MS Style Guide	Repeat noun when "it" or "this" is unclear

Grammar Rules (R11-R13)

These grammar rules ensure consistency in punctuation, capitalization, and number formatting across all Qt documentation. Based on QUIP 25 (S2), Qt Writing Guidelines (S1), and Microsoft Writing Style Guide (S9).

Rule	Summary	Sources	Notes
R11	Use serial (Oxford) comma	QUIP 25, Qt Writing Guidelines	"name, value, and type" not "name, value and type"
R12	Use sentence-case for titles	Qt Writing Guidelines, QUIP 25, MS Style Guide	"Getting started with Qt Quick" not "Getting Started With Qt Quick"
R13	Numbers: spell out 1-9	QUIP 25	Numerals for 10+, dimensions, versions, code values

API Documentation (R14-R19)

These rules define the required patterns for documenting C++ and QML APIs. They ensure consistency in how classes, functions, properties, and signals are documented. Based on C++ Documentation Style (S3), QML Documentation Style (S4), and QDoc Manual (S10).

Rule	Summary	Sources	Notes
R14	\brief scope	C++ Doc Style, QML Doc Style, QDoc Manual	MANDATORY for: \class, \qmltype, \property, \qmlproperty, \example, \page. Recommended for: \fn, \qmlmethod, \qmlsignal, \enum
R15	Briefs end with period	C++ Doc Style, QML Doc Style	Applies to all briefs that are provided
R16	Class/Type documentation	C++ Doc Style, QML Doc Style, QDoc Manual	Requires: \class/\qmltype, \brief, \inmodule/\inqmlmodule, \since
R17	Function brief patterns	C++ Doc Style, QML Doc Style	Start with verb: "Returns...", "Sets...", "Constructs...". Brief recommended, not mandatory.
R18	Property brief patterns	C++ Doc Style, QML Doc Style	"This property holds...". Brief is mandatory for properties.
R19	Signal brief patterns	C++ Doc Style, QML Doc Style	"This signal is emitted when...". Brief recommended, not mandatory.

Example Documentation (R20-R23)

These rules define the required elements and quality standards for Qt example documentation. Every example must meet these requirements before being included in Qt releases. Based on Writing Example Documentation and Tutorials (S6) and Qt Examples Guidelines (S5).

Rule	Summary	Sources	Notes
R20	11 mandatory elements	Writing Example Documentation	Title, \example, \brief, \examplecategory, image, overview, running instructions, platform notes, main content, references, licenses
R21	Zero warnings	Qt Examples Guidelines	C++ compiler and qmllint must produce no warnings
R22	Screenshot specs	Qt Examples Guidelines	Minimum 440×320 pixels, icons 64×64, high DPI, WebP format
R23	Title guidelines	Qt Examples Guidelines, Writing Example Documentation	Don't repeat "Example" or module name in title

Alt Text (R24-R27)

These rules ensure images in Qt documentation are accessible to users with visual impairments. Alt text describes images for screen readers and appears when images fail to load. Based on QDoc Style Guidelines (S8) and QUIP 21.

Rule	Summary	Sources	Notes
R24	Format: capital letter, no period	QDoc Style Guidelines, QUIP 21	{Window with toolbar and buttons}
R25	Priority order	QDoc Style Guidelines	1. Visible text/labels 2. Context/purpose 3. Visual description
R26	Use generic UI terms	QDoc Style Guidelines	"button" not "Button", "dialog" not "Dialog"
R27	Use descriptive phrases	QDoc Style Guidelines	Noun phrases, not full sentences

Writing Contexts (R28-R29)

Different types of Qt documentation require different writing styles. API reference documentation is formal and technical, while tutorials are conversational and instructional. These rules help you choose the right style for each context. Based on C++ Documentation Style (S3), QML Documentation Style (S4), Qt Writing Guidelines (S1), and Writing Example Documentation and Tutorials (S6).

Rule	Summary	Sources	Notes
R28	API documentation style	C++ Doc Style, QML Doc Style	Present tense, imperative briefs, indicative descriptions, no "you"
R28b	Tools documentation style	Qt Writing Guidelines	Present tense, "you" acceptable, UI elements in bold, menu paths with >
R29	User guide/tutorial style	Qt Writing Guidelines, Writing Example Documentation	Use "you", explain concepts, less jargon

Common Mistakes (R30-R37)

This quick reference lists the most frequent documentation errors and their corrections. Use this as a checklist when reviewing documentation. Each mistake references the rule that explains the correct approach.

Rule	Mistake	Correction	Cross-ref
R30	Passive voice	Use active voice	R1
R31	Future tense	Use present tense	R4
R32	Wordy phrases	Be concise	R2
R33	Ambiguous "this"	Be specific	R10
R34	Inconsistent terms	Pick one term	R8
R35	Missing \brief on class/type/property	Add \brief	R14
R36	Brief without period	Add period	R15
R37	"Neutral voice"	Use "imperative mood" or "indicative mood"	QUIP 25

Common Substitutions (R38)

This section lists words and phrases to avoid in Qt documentation, along with their preferred alternatives. These substitutions improve clarity and accessibility for international readers. Based on QUIP 25 (S2) and Microsoft Writing Style Guide (S9).

Latin Terms (Always Avoid)

Latin abbreviations are not universally understood. Replace them with plain English equivalents.

Instead of	Use	Source
e.g.	for example, such as, like	MS Style Guide
i.e.	that is	MS Style Guide
etc.	(be specific, or use "such as" + examples)	MS Style Guide
via	through, using, with, by	QUIP 25, MS Style Guide
per	according to, for each	—
versus, vs.	compared to, or, against	—

Verbose Phrases

Replace wordy phrases with concise alternatives to improve readability.

Instead of	Use	Source
In order to	To	QUIP 25, MS Style Guide
It is possible to	You can / Can	QUIP 25
Make use of	Use	MS Style Guide
At this point in time	Now	—
Due to the fact that	Because	—
Is able to	Can	—

Hedging Words (Avoid)

These words can be condescending or assume reader knowledge. Avoid them in most contexts.

Avoid	Reason	Source
simply, just	Implies task is trivial	QUIP 25
obviously, clearly	Assumes reader knowledge	QUIP 25
easily	May not be easy for reader	QUIP 25
please	Use only for inconvenient requests	QUIP 25

Terminology

Use Qt's preferred terminology for consistency across all documentation.

Instead of	Use	Source
programmer	developer	QUIP 25
since, as (for causation)	because	QUIP 25, MS Style Guide
utilize	use	MS Style Guide

QDoc Formatting (R39-R41)

These rules cover QDoc-specific formatting conventions, including command syntax and line length limits. Based on QDoc Style Guidelines (S8) and Qt Coding Style.

Rule	Summary	Sources	Enforcement
R39	No space before curly brace	QDoc Style Guidelines	Recommended for compact text. \l{QWidget} preferred over \l {QWidget} . Not strictly enforced.
R40	80-column line length	Qt Coding Style, QDoc Style Guidelines	CI-enforced. For documentation comments and .qdoc files.
R41	\sa targets must match page titles	Qt Doc Team practice	Required. Verify targets resolve to actual pages.

UI and Tools Documentation (R42-R44)

These rules apply specifically to documentation for Qt tools like Qt Creator and Qt Design Studio. They cover how to format UI elements, keyboard shortcuts, and menu paths. Based on Qt Writing Guidelines (S1) and Qt Creator documentation conventions.

Rule	Summary	Sources	Notes
R42	UI element markup	Qt Writing Guidelines, Qt Creator docs	Bold for UI elements: File > New Project. In QDoc: \uicontrol{element}
R43	Keyboard shortcut formatting	Qt Creator docs	Ctrl+B , sequential: Ctrl+K, Ctrl+D , platform: Ctrl+O ( Cmd+O on macOS)
R44	Menu path formatting	Qt Creator docs	Go to File > New Project > Qt Quick Application

Qt Product and Module Names (R3 Detail)

Official Qt product and module names must use correct capitalization and spelling. This ensures consistency and brand accuracy across all documentation. Per Qt Terms and Concepts (S7).

Correct	Incorrect	Notes
Qt GUI	Qt Gui, Qt gui	Acronyms all caps
Qt SQL	Qt Sql	Acronym all caps
Qt SVG	Qt Svg	Acronym all caps
Qt XML	Qt Xml	Acronym all caps
Qt Quick	QtQuick (in prose)	Two words in prose
Qt Add-Ons	Qt Addon, Qt Addons	Hyphenated
Qt D-Bus	Qt DBus, Qt DBUS	Hyphenated
Qt Creator	QtCreator	Two words
QDoc	Qdoc, qdoc	CamelCase

Compound Words (R3 Detail)

Qt documentation uses specific compound word conventions. Use these spellings consistently.

Correct	Incorrect
checkbox	check box
filename	file name
namespace	name space
runtime	run time, run-time
framerate	frame rate
toolchain	tool chain
codebase	code base
standalone	stand-alone

Tools-Specific Terminology (R3 Detail)

Qt Creator and Qt Design Studio use specific terminology that should be used consistently in tools documentation.

Term	Correct Usage	Context
kit	kit (not "configuration set")	Qt Creator
toolchain	toolchain (not "tool chain")	All
build system	build system (not "buildsystem")	All
mode	Edit mode, Design mode, Debug mode	Qt Creator, Qt Design Studio

Enforcement Levels

Rules have different enforcement levels. Understanding these helps prioritize compliance efforts.

Level	Meaning	Examples
CI-enforced	Checked automatically by CI; will fail builds	R40 (80-column)
Required	Must be followed; causes warnings or broken docs	R14 (mandatory \brief), R41 (\sa targets)
Recommended	Should be followed; not strictly enforced	R39 (no space before brace)

Notes

When sources conflict, follow hierarchy: Qt Writing Guidelines → QUIP 25 → C++/QML Doc Style → MS Style Guide
QDoc Manual is authoritative for syntax only, not style
\brief is mandatory only for classes, QML types, properties, and examples
\brief is recommended (not mandatory) for functions, signals, enums, and methods