Qt Writing Guidelines: Difference between revisions
No edit summary |
|||
| Line 14: | Line 14: | ||
# 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 [[ | # 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 22: | Line 22: | ||
!Instead of | !Instead of | ||
|- | |- | ||
| | |||
| | | | ||
|- | |- | ||
| Line 33: | Line 34: | ||
|ergo | |ergo | ||
|} | |} | ||
== Writing API Documentation == | == Writing API Documentation == | ||
| Line 56: | Line 55: | ||
[[ExamplesDocumentationStyle| Examples and Tutorials Style]] | [[ExamplesDocumentationStyle| Examples and Tutorials Style]] | ||
When writing Qt documentation, ensure that new Qt 5 modules conform to the requirements: | When writing Qt documentation, ensure that new Qt 5 modules conform to the requirements: | ||
== Qt 5 Documentation Requirements == | == Qt 5 Documentation Requirements == | ||
| Line 70: | Line 63: | ||
QDoc changes should pass the [[QDocRegressionTesting]] | QDoc changes should pass the [[QDocRegressionTesting]] | ||
== Using images in documentation == | == 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. | 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. | 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. | ||
Revision as of 15:18, 15 October 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.
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:
- 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
- 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 |
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.
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 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
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.