Writing Example Documentation and Tutorials

This page is part of the Qt Writing Guidelines.

Qt documentation follows the Qt Project's QUIP policy system.

In particular, QUIP-13 specifies the construction of the example, how to name the files, and other conventions that examples should follow.

This wiki adds more information about documenting the examples and about the minimum set of information for writing example documentation and tutorials.

• QUIP-13 Qt Examples

Qt Documentation includes example documentation and tutorials. QDoc is the tool in Qt for writing, generating, and publishing documentation. For starters, familiarize yourself to the QDoc manual and the Qt Writing Guidelines.

• QDoc Manual
• Contributing Examples to Qt

Example Documentation and Tutorials

Qt 6 examples have an accompanying example documentation. This documentation should describe the example's themes and Qt modules or tools. An accompanying image is important to show UI related elements and the expected output should be clear.

A tutorial goes beyond a description, outlining particular steps and highlighting the important parts of the example. The tutorial should walk through the code and write about topics related to Qt. Notes and other information should supplement the walk-through, giving insight and reason for the particular code.

Essentially, the minimum example documentation should contain:

1. Title - QDoc's \title command. The title should be simple and descriptive.
2. Example page - QDoc's \example command creates the example page. The \example command specifies the directory.
3. Brief description - \brief command and a small description of the example's theme. Complete the sentence and end with a period.
4. Example category - \examplecategory macro assigns the example in category from within Qt Creator. See Qt Examples in Qt Creator.
5. Image - especially useful for GUI related examples. Qt Creator can show these images as thumbnails.
6. Overview - one or several paragraphs that describe the objective of the example, as well as the Qt technologies and tools used.
7. Running instruction - describe where to find the example (see Sample Text: Running Instruction section below).
8. Platform notes - mention the relevant platforms that the example can be run on. Mention any platform limitations.
9. Main body - one or several paragraphs that describe the example's themes and expected behavior.
10. References - add links to related documentation, overview, or other supplementary material.
11. Licenses - add the Commercial/BSD 3 clause license (example code) or the Commercial/GFDL 1.3 (documentation files).

Application Examples Template

Use the app-examples-template.qdoc template file to write documentation for application examples.

This template is located in qtbase/doc/src/global/app-examples-template.

The minimum tutorial fulfills the minimum example documentation in addition to the following:

1. Code snippets - show and analyze the code in a granular (line-by-line) or holistic (the principle and goal) way.
2. Step-by-step instruction - show the progression from start to finish. A similar style is meal recipes, but do not follow strictly.
3. Insight - provide insight to the code structure and Qt usage. Include common themes in the insight such as code security, scalability, usability, and so on.
4. Verb-focused title - Emphasize the action or verb in the title. Use the progressive form, typically ending in -ing. For example, drawing, integrating, handling, processing, and so on.

The sections below provide sample text for the requirements for example documentation and tutorial

Sample Text: Running Instruction

Example documentation and tutorials should outline the requirements and steps for building and running the example. Ideally, Qt Creator can open and launch the example, but some examples may need additional tools or environment.

We aim for consistency and the following text is appropriate to inform about running examples from within Qt Creator. Feel free to modify and adapt to the specific example.

At the bottom of your example documentation (same area as the \page command), add:

\include examples-run.qdocinc

QDoc will copy the contents from qtbase/doc/global and automatically create a section about running the example.

\section1 Running the Example

To run the example from \l{Qt Creator Manual}{Qt Creator}, open the Welcome
mode and select the example from Examples. For more information, visit
{Qt Creator: Building and Running an Example}{Building and Running an Example}.

Sample Text: Licenses

Qt licenses are at the top of each file. Make sure the year is correct.

For example code, use the Commercial/BSD 3 clause license:

// Copyright (C) 2024 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause

The example documentation and tutorial can be under a specific Commercial/GFDL 1.3 documentation license:

// Copyright (C) 2024 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only

Adding Images

Images are useful for demonstrating UI elements and for showing the current state of the example.

Follow QUIP-21 for the policy for images.

• QUIP-21 - Using images in Qt documentation

You should add an alt-text to images. The alt-text fills the HTML's alt attribute for screen readers and accessibility tools. Start capitalized and do not end with a period.

\image imagename.webp {A Window with a blue background}

Examples

Here are recent examples that demonstrate how a tutorial should be written.

• File System Explorer
• Calqlatr
• Windows Embedding