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: Category:Developing Qt::Documentation

Language Style

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.

Tip: Say the text out loud. If it sounds weird, then it is weird...then it may also be wrong.

Here are some specifics for Qt:

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 the correct spelling and case for Qt Products. See Qt Terms and Concepts.
6. Be consistent with forming lists (\list). Use the same tone or mode and be consistent ending with periods.
7. Use US spelling and avoid latin abbreviations. See Use US spelling and avoid non-English words. Here is a summary :

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

Translated Documentation

New in Qt 6.8, the Qt Reference Documentation is available in translated formats. Think about how translatable the sentence you are writing. If the text is too complicated, then it may confuse the reader.

Creating Hierarchy in Documentation

Documentation needs to have structure and hierarchy for readability. Form topics and ideas separately and supplement with follow up sentences related to the topic.

Here is an example of structured overview, This also applies to documentation that is written into paragraphs.

Title (\title)

Introductory parapraph. Description about what the page is about.

Topic 1 (\section1)

• Topic 1 paragraph 1. Sentence related to paragraph 1. Another sentence related to paragraph 1.
• Topic 1 paragraph 2. Sentence related to paragraph 2. Another sentence related to paragraph 2.

Topic 2 (\section1)

• Topic 2 paragraph 1. Sentence related to paragraph 1. Another sentence related to paragraph 1.
• Topic 2 paragraph 2. Sentence related to paragraph 2. Another sentence related to paragraph 2.

References/See Also (\section1)

• List of relevant pages.

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

For designing Qt APIs, visit:

• API Design Principles

Using QDoc to Write Documentation

These QDoc guidelines complement the QDoc Manual

• Style Guidelines - proper use of commands, code blocks, markup, and indentation
• Linking Guidelines
• QDoc Project Templates
• Checklist for Adding Documentation for a New Module
• Documentation Structure page contains a map of how the directory structure of a repository or module

Using QDoc \note and \warning

This is a prevalent issue that warrants its own section.

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

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 1-sentence 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.

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

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 examples, documenting examples, 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.

See Also

• Qt 5 Documentation - for creators of Qt 5 documentation

QDoc changes should pass the QDocRegressionTesting