Qt Writing Guidelines

The Qt Writing Guidelines contains information about writing Qt documentation in a consistent way. Though there are exceptions, maintain the consistency level outlined in the guidelines or the existing Qt documentation.

This guideline is maintained by the Qt Documentation Team, with members across the different Qt Group sites. Visit their page at: Contributing to Qt Documentation

Language style

Say the text out loud. If it sounds weird, then it is weird...and may need editing.

Qt uses the Microsoft Writing Style Guide in the Qt documentation. Essentially, use clear and direct language in American English. We write to a diverse audience and we need to communicate Qt topics in an approachable and understandable manner.

Here are some specifics for Qt:

Use active voice, not passive. Passive does not make a sentence formal, but unnecessarily weakens the sentence. See Verbs
Use the pronoun you in to address the reader when appropriate. See Nouns and Pronouns.
Use because instead of since or as. See Use simple words, concise sentences.
Use a serial comma, also known as the Oxford comma. See Commas.
Use the correct spelling and case for Qt Products. See Qt Terms and Concepts.
Be consistent with forming lists (\list). Use the same tone or mode and be consistent about ending with periods.
Use US spelling and avoid latin abbreviations. See Use US spelling and avoid non-English words. Here is a summary :


Use	Do not use
that is	i.e.
for example	e.g.
and so on.	etc.
through, using	via
advice, warning	caveat

Translated Documentation

New in Qt 6.8, the Qt Reference Documentation is available in translated formats. Choose words that is simpler to translate or interpret. If the text is too complicated, then it may be poorly translated by translation tools.

Writing API documentation with QDoc

We document Qt APIs in the sources and use QDoc to generate the HTML for the doc.qt.io site and an offline version for Qt Creator. These QDoc guidelines complement the QDoc Manual

C++ and QML documentation follow a similar style, but there are differences.

Visit the following pages for documenting APIs

General syntax related guidelines

Quoting code using snippets

Make sure your snippet compiles and runs.

It is best to include code snippets using the \snippet <filename> command. We are striving to include compilable and usable code in the Qt documentation. If the code is inside a source file, then we can quote the code from overviews, tutorials, and API documentation.

Read the QDoc Manual about the other commands relating to including sources in documentation. See Including External Code

The previous guideline about using \code and \endcode is no longer preferred, though it is still possible to use these commands.

For quoting input or output text (from the terminal, for example), use the various quotation commands. See Including Code Inline

Using markup for code and UI texts

Mark up text or code to indicate to the reader that the text is special...such as code or text visible to the application user.

These are the common markup commands in Qt documentation:

\c command for marking code such as default values or output. Rendered in monospace font.
\uicontrol command for UI text visible to application users. Rendered in bold.

See Text Markup for other markup commands

The code below generates the documentation for QWidget::focusNextChild():

/*!
    \fn bool QWidget::focusNextChild()

    Finds a new widget to give the keyboard focus to, as appropriate
    for \uicontrol Tab, and returns \c true if it can find a new widget, or
    false if it can't.

    \sa focusPreviousChild()
*/

Writing section titles

Consistency is key...write sections in sentence-case, but maintain consistency with existing pages.

Section titles are written as arguments to \section1 and \section2 commands.

Write section titles in sentence-case as indicated by the Microsoft Writing Style Guide. See Formatting titles.

The previous guideline about using title-case is no longer valid, but maintain consistency within the page for readability and neatness.

Task-based titles

In Qt, the section title could be about performing tasks or a description of a sub-system.

Here are some suggestions:

For sections about performing tasks, use verbs in progressive form: Building..., Using..., Creating..., Connecting..., and so on.
For sections about a sub-system or a description, use nouns: Coordinate systems, Chart types, Dynamic properties, and so on.

Linking issues with section titles

Choose unique titles to avoid linking problems.

QDoc uses section titles as link targets, and a common issue is mis-linking to unwanted sections. This issue is because QDoc links to titles that already exist.

Search for already existing titles, run QDoc, and check the HTML output for missing or misdirected links.

Using QDoc \note and \warning

Only noteworthy statements belong in a \note.

QDoc has a \note command that creates a stylized Note: in the documentation. Similarly, \warning creates a Warning: .

Use them sparingly but be aware of their intended use and consequences.

Notes and warnings break the flow of the paragraph or section, creating an aside or detour from the usual topic
\note is only for short statements. See \note command in the QDoc manual
Reserve \warning for critical information that lead to serious consequences

Think of the hierarchy of information. When highlighting several important content, only have the most important statement in a \note. Notes that are not critical may not be that important.

The general hierachy of information, in order of highlighted importance, is:

Statement → Advice → Note → Warning

Instead, integrate the note into a paragraph. A one-line paragraph dangling in a page is better than the overuse of notes.

Use a list if there are several notes after each other. For example, add \section1 Additional notes: at the end of your page to collect the notes.

For example:

Additional notes:
Statement A

Statement B

Statement C

Documenting examples

Qt Examples are an important part of the Qt Framework. They show how the framework is to be used and inspire developers about possibilities with Qt. These pages help with creating, documenting, and how to contribute examples into the Qt repositories.

Qt Examples Guidelines - do's and don'ts for examples

Writing Example Documentation and Tutorials - writing example documentation and tutorials
Contributing Examples to Qt - configuring an example for integration into the Qt repositories
Qt Examples in Qt Creator - ensuring that the example works within Qt Creator

Including images

The requirements for images in Qt documentation is outlined in QUIP-21.

QUIP-21 Using images in Qt documentation

Linting with Vale

Vale is a linter that detects improper use of language and can make suggestions in-place. Vale has command-line interface and is also available for Qt Creator and VS Code.

For more information about Vale, visit Setting Up Vale.

Testing and submitting documentation

Before pushing a change into codereview.qt-project.io, go over the following guidelines. These guidelines help with smoother documentation integration.

Checklist for Adding Documentation for a New Module
Documentation Structure page contains a map of how the directory structure of a repository or module
QDoc Regression Testing - test the content before you push a patch to codereview.qt-project.io