Qt Writing Guidelines: Difference between revisions

From Qt Wiki
Jump to navigation Jump to search
No edit summary
 
(34 intermediate revisions by the same user not shown)
Line 1: Line 1:
[[Category:Writing Guidelines]]
[[Category: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.
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 ==
== Language Style ==
Line 8: Line 10:




Here are some clarifications for Qt documentation:
Here are some specifics for Qt:


# Use '''active voice''', not passive. Passive does not make a sentence formal, but unnecessarily weakens the sentence. See [https://learn.microsoft.com/en-us/style-guide/grammar/verbs Verbs]
# Use '''active voice''', not passive. Passive does not make a sentence formal, but unnecessarily weakens the sentence. See [https://learn.microsoft.com/en-us/style-guide/grammar/verbs Verbs]
Line 14: Line 16:
# Use '''because''' instead of "since" or "as". See [https://learn.microsoft.com/en-us/style-guide/word-choice/use-simple-words-concise-sentences Use simple words, concise sentences].
# Use '''because''' instead of "since" or "as". See [https://learn.microsoft.com/en-us/style-guide/word-choice/use-simple-words-concise-sentences Use simple words, concise sentences].
# Use a serial comma, also known as the '''Oxford comma'''. See [https://learn.microsoft.com/en-us/style-guide/punctuation/commas Commas]
# Use a serial comma, also known as the '''Oxford comma'''. See [https://learn.microsoft.com/en-us/style-guide/punctuation/commas Commas]
# Use the correct spelling and case for Qt Products. See [[Qt Terms and Concepts]]
# Use US spelling and avoid latin abbreviations. See [https://learn.microsoft.com/en-us/style-guide/word-choice/use-us-spelling-avoid-non-english-words Use US spelling and avoid non-English words]. Here is a summary :
# Use US spelling and avoid latin abbreviations. See [https://learn.microsoft.com/en-us/style-guide/word-choice/use-us-spelling-avoid-non-english-words Use US spelling and avoid non-English words]. Here is a summary :


Line 20: Line 23:
!Use
!Use
!Instead of
!Instead of
|-
|for example
|e.g.
|-
|-
|that is
|that is
Line 34: Line 34:
|}
|}


*
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
* [[Spelling_Module_Names_in_Qt_Documentation | Spelling Qt Module Names]]
 
it may confuse the reader.
 
'''Tip: ''Say the text out loud. If it sounds weird, then it is weird...then it may also be wrong.'''''
 
== Vale Support ==
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]].


== Writing API Documentation ==
== 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.
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++ and QML documentation follow a similar style, but there are differences. See the following pages for documenting APIs.


*[[CppDocumentationStyle | C++ Documentation Style]]
* [https://doc.qt.io/qt-6/qtwritingstyle-cpp.html C++ Documentation Style]
* [[QMLDocumentationStyle | QML Documentation Style]]
* [https://doc.qt.io/qt-6/qtwritingstyle-qml.html QML Documentation Style]


== Writing the QDoc files ==
For designing Qt APIs, visit:


These QDoc guidelines complement the [http://doc.qt.io/qt-5/qdoc-index.html QDoc Manual]
* [[API Design Principles]]
 
== Using QDoc to Write Documentation ==
 
These '''QDoc''' guidelines complement the [http://doc.qt.io/qt-5/qdoc-index.html QDoc Manual]


* [[QDocStyleGuidelines | Style Guidelines]] - proper use of commands, code blocks, markup, and indentation
* [[QDocStyleGuidelines | Style Guidelines]] - proper use of commands, code blocks, markup, and indentation
* [[QDocLinkingGuidelines | Linking Guidelines ]]
* [[QDocLinkingGuidelines | Linking Guidelines]]
* [[QDocExamples | Integrating Examples]]
* [[ QDoc Project Templates]]
* [[QDoc_Project_Templates | QDoc Project Templates]]
* [[Checklist for Adding Documentation for a New Module]]
* [[Qt_Documentation_Structure | Documentation Structure]] page contains a map of how the directory structure of a repository or module


== Documenting Examples ==
== Using QDoc \note and \warning ==
[[ExamplesDocumentationStyle| Examples and Tutorials Style]]
''This is a prevalent issue that warrants its own section.'' 
When writing Qt documentation, ensure that new Qt 5 modules conform to the requirements:
 
* [[Qt5DocumentationProject | Qt 5 Documentation]]
QDoc has a '''\note''' command that creates a stylized '''Note:''' in the documentation. Similarly '''\warning''' creates a '''Warning:''' in the documentation.
* [[Checklist for Adding Documentation for a New Module]]
* [[Qt_Documentation_Structure | Documentation Structure]] page contains a map of how the directory structure of a repository or module should be


QDoc changes should pass the [[QDocRegressionTesting]]
Use them sparingly but be aware of their intended use and consequences.


== Qt 5 Documentation Requirements ==
* 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 [https://doc.qt.io/qt-6/11-qdoc-commands-specialcontent.html#note \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 in a \note. Notes that are not critical may not be that important.


When writing Qt documentation, ensure that new Qt 5 modules conform to the requirements:
Instead, '''integrate the sentence or statement into a paragraph'''. A one-line paragraph dangling in a page is better than the overuse of notes.
* [[Qt5DocumentationProject | Qt 5 Documentation]]
* [[Checklist for Adding Documentation for a New Module]]
* [[Qt_Documentation_Structure | Documentation Structure]] page contains a map of how the directory structure of a repository or module should be


QDoc changes should pass the [[QDocRegressionTesting]]
== 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


== Licensing Qt Reference Documentation ==
* [[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


We distribute documentation, examples, or snippets under the following licenses:
== Including Images ==
* GNU Free Documentation License: for pure documentation (typically in .qdoc files)
The requirements for images in Qt documentation is outlined in QUIP-21.
* 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.
* [https://contribute.qt-project.org/quips/21 QUIP-21] '''Using images in Qt documentation'''


== Todo: Remove this section when the rest is finished ==
== Qt 5 Documentation Requirements ==


* [http://wiki.qt.io/Category:Developing_Qt::Documentation Qt Documentation Wiki] - the main Documentation wiki which contains style information and contribution details. '''Also contains contact information for the Qt Documentation Team'''
For Qt 5 documentation, or those who create documentation using Qt 5, see the following pages:
* [http://doc.qt.io/qt-5/qdoc-index.html QDoc Manual] - contains a guide to QDoc as well as information about C++ and QML commands
* [[Qt5DocumentationProject | Qt 5 Documentation]]
* [[ Building Qt Documentation]] - outlines how to build the documentation for Qt 5 and for each module
* [http://doc-snapshots.qt.io/ 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. [https://contribute.qt-project.org/quips/21 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.
QDoc changes should pass the [[QDocRegressionTesting]]

Latest revision as of 15:50, 21 November 2024

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

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

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.

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

Vale Support

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.

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.

For designing Qt APIs, visit:

Using QDoc to Write Documentation

These QDoc guidelines complement the QDoc Manual

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

Including Images

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

  • QUIP-21 Using images in Qt documentation

Qt 5 Documentation Requirements

For Qt 5 documentation, or those who create documentation using Qt 5, see the following pages:

QDoc changes should pass the QDocRegressionTesting

Retrieved from "https://wiki.qt.io/index.php?title=Qt_Writing_Guidelines&oldid=43287"