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.

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

Sources

ID	Source	URL
S1	Qt Writing Guidelines	https://wiki.qt.io/Qt_Writing_Guidelines
S2	QUIP 25 - Documentation Writing Style	https://code.qt.io/cgit/meta/quips.git/plain/quip-0025-Documentation-Writing-Style.rst
S3	C++ Documentation Style	https://wiki.qt.io/C%2B%2B_Documentation_Style
S4	QML Documentation Style	https://wiki.qt.io/QML_Documentation_Style
S5	Qt Examples Guidelines	https://wiki.qt.io/Qt_Examples_Guidelines
S6	Writing Example Documentation and Tutorials	https://wiki.qt.io/Writing_Example_Documentation_and_Tutorials
S7	Qt Terms and Concepts	https://wiki.qt.io/Qt_Terms_and_Concepts
S8	QDoc Style Guidelines	https://wiki.qt.io/QDoc_Style_Guidelines
S9	Microsoft Writing Style Guide	https://learn.microsoft.com/en-us/style-guide/welcome/
S10	QDoc Manual	https://doc.qt.io/qt-6/qdoc-index.html

API Documentation Requirements Matrix

This matrix shows mandatory vs recommended elements by documentation type (from S3, S4):

Element	\brief	\since	\inmodule / \inqmlmodule	Other Requirements
\class	MANDATORY	MANDATORY	MANDATORY	—
\qmltype	MANDATORY	MANDATORY	MANDATORY	—
\property	MANDATORY	MANDATORY	—	—
\qmlproperty	MANDATORY	Recommended	—	—
\fn (function)	Recommended	MANDATORY	—	\a params, \c values
\qmlmethod	Recommended	Recommended	—	\a params
\fn (signal)	Recommended	Recommended	—	—
\qmlsignal	Recommended	Recommended	—	—
\enum	Recommended	Recommended	—	\value for each value
\example	MANDATORY	—	—	\title , \examplecategory

Core Principles (R1-R10)

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

Grammar Rules (R11-R13)

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

API Documentation (R14-R19)

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

Example Documentation (R20-R23)

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

Alt Text (R24-R27)

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

Writing Contexts (R28-R29)

Rule	Summary	Sources	Notes
R28	API documentation style	S3, S4	Present tense, imperative briefs, indicative descriptions, no "you"
R28b	Tools documentation style	S1	Present tense, "you" acceptable, UI elements in bold, menu paths with >
R29	User guide/tutorial style	S1, S6	Use "you", explain concepts, less jargon

Common Mistakes (R30-R37)

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"	S2

Common Substitutions (R38)

Latin Terms (Always Avoid)

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

Verbose Phrases

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

Hedging Words (Avoid)

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

Terminology

Instead of	Use	Source
programmer	developer	S2
since, as (for causation)	because	S2, S9
utilize	use	S9

QDoc Formatting (R39-R41)

Rule	Summary	Sources	Notes
R39	No space before curly brace	S8	\l{QWidget} not \l {QWidget} . Note: QDoc Manual examples show spaces, but S8 wiki takes precedence.
R40	80-column line length	Qt Coding Style, S8	For documentation comments and .qdoc files
R41	\sa targets must match page titles	Qt Doc Team practice	Verify targets resolve to actual pages

UI and Tools Documentation (R42-R44)

Rule	Summary	Sources	Notes
R42	UI element markup	S1, 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)

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

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)

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

Notes

When sources conflict, follow hierarchy: S1 → S2 → S3/S4 → S9
QDoc Manual (S10) 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