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.

Language Style

We use 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 clarifications for Qt documentation:

1. Use active voice, not passive. Passive does not make a sentence formal, but unnecessarily weakens the sentence. See Verbs
2. Use the pronoun you in to address the reader when appropriate. See Nouns and Pronouns.
3. Use because instead of "since" or "as". See Use simple words, concise sentences.
4. Use a serial comma, also known as the Oxford comma. See Commas
5. Use US spelling and avoid latin abbreviations. See Use US spelling and avoid non-English words. Here is a summary :

Use	Instead of
for example	e.g.
that is	i.e.
namely	viz.
therefore	ergo

• Spelling Qt Module Names

Writing API Documentation

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.

C++ and QML documentation follow a similar style, but there are differences. See the following pages for documenting APIs.

• C++ Documentation Style
• QML Documentation Style

Writing the QDoc files

These QDoc guidelines complement the QDoc Manual

• Style Guidelines - proper use of commands, code blocks, markup, and indentation
• Linking Guidelines
• Integrating Examples
• QDoc Project Templates

Documenting Examples

Examples and Tutorials Style When writing Qt documentation, ensure that new Qt 5 modules conform to the requirements:

• Qt 5 Documentation
• Checklist for Adding Documentation for a New Module
• Documentation Structure page contains a map of how the directory structure of a repository or module should be

QDoc changes should pass the QDocRegressionTesting

Qt 5 Documentation Requirements

When writing Qt documentation, ensure that new Qt 5 modules conform to the requirements:

• Qt 5 Documentation
• Checklist for Adding Documentation for a New Module
• Documentation Structure page contains a map of how the directory structure of a repository or module should be

QDoc changes should pass the QDocRegressionTesting

Licensing Qt Reference Documentation

We distribute documentation, examples, or snippets under the following licenses:

• GNU Free Documentation License: for pure documentation (typically in .qdoc files)
• BSD 3-Clause License: for snippet documentation and examples
• LGPL: for demo applications and when LGPL is warranted

The header for the licenses are located in qtbase and should be pasted on the top of the files.

Todo: Remove this section when the rest is finished

• Qt Documentation Wiki - the main Documentation wiki which contains style information and contribution details. Also contains contact information for the Qt Documentation Team
• QDoc Manual - contains a guide to QDoc as well as information about C++ and QML commands
• Building Qt Documentation - outlines how to build the documentation for Qt 5 and for each module
• doc-snapshots.qt.io - the documentation snapshot

Using images in documentation

It can be useful to include images in documentation, such as screenshots, diagrams, icons, or even animated images and embedded YouTube videos. QUIP-21 describes the requirements and considerations for use of images in Qt's documentation.

As the images must be checked in to git, the binary blob size is a point of some concern. Prefer the webp image format when possible, and crop out unnecessary details to reduce the overall size.