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.

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

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 only. Not in API 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

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

Rule	Summary	Sources	Notes
R14	\brief is mandatory	S3, S4, S10	QDoc generates warnings if brief is empty
R15	All briefs end with period	S3, S4	Required punctuation
R16	Class documentation requirements	S3, S10	Requires: \class, \brief, \inmodule, \since. Document in .cpp files.
R17	Function briefs start with verb	S3, S4	"Returns...", "Sets...", "Constructs...", "Destroys..."
R18	Property brief patterns	S3, S4	"This property holds...", "This property describes..."
R19	Signal brief patterns	S3, S4	"This signal is emitted when...", "Emitted when..."

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
R23	Title guidelines	S5, S6	Don't repeat "Example" or module name in title

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

Rule	Summary	Sources	Notes
R28	API documentation style	S3, S4	Present tense, imperative briefs, indicative descriptions, no "you"
R29	User guide/tutorial style	S1, S6	Use "you", explain concepts, less jargon

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	Always include	R14
R36	Brief without period	Add period	R15
R37	"Neutral voice"	Use "imperative mood" or "indicative mood"	S2

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	—

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

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

Per S7: