Overview

This QUIP establishes guidelines for the writing style used in Qt documentation, focusing on tone, grammar, language usage, and readability.

Introduction

Clear and consistent writing is essential for Qt documentation. This document defines the writing style standards that ensure Qt documentation is professional, accessible, and easy to understand for users worldwide.

General Principles

Qt documentation should:

• Be correct.
• Be clear, concise, and unambiguous.
• Be task-oriented, helping users accomplish specific goals efficiently.
• Use consistent terminology throughout.
• Be accessible to non-native English speakers and inclusive of diverse cognitive, visual, and physical needs.
• Maintain a professional yet approachable tone.
• Focus on what users need to know.

Language Standards

Style Guide Reference

When you write Qt documentation, follow this QUIP as the primary reference for English language usage. If this QUIP does not address a specific issue, you can consult Microsoft Writing Style Guide, but following it is not mandatory.

English Variant

Use American English spelling and terminology consistently, for example:

• “color” not “colour”.
• “initialize” not “initialise”.
• “dialog” not “dialogue”.

Exception: When referring to specific API names that use British spelling, preserve the original spelling.

Grammar and Usage

Voice and Tense

• Use active voice whenever possible:

  Use: “The function returns a pointer”.

  Avoid: “A pointer is returned by the function”.

• Use present tense whenever possible.

  Use: “This saves the file”.

  Avoid: “This will save the file”.

Sentence Structure

• Write complete sentences, even in bulleted lists whenever possible.
• Keep sentences concise (aim for 20 words or fewer).
• Place the most important information first.

Person and Pronouns

• In general, use second person (“you”), write as though you’re speaking to the reader.
• Avoid first person (“I”, “we”) except in tutorials and examples.
• Use “Qt” or “the framework” instead of “we” when referring to Qt itself.

Word Choice

Clarity Over Complexity

• Choose simple, clear words over complex alternatives.
• Define technical terms on first use.
• Avoid jargon unless necessary for precision.
• Spell out abbreviations on first use, followed by the abbreviation in parentheses (excluding widely recognized terms).

Consistency

Use these preferred terms consistently:

• “developer” not “programmer” or “coder”.
• “user” for end-users (however, remember to use second person in most cases).

Terms for UI and keyboard interactions

• Select: Use for describing selecting things in a UI. This can be buttons, checkboxes, values from lists, and so on.
• Clear: Use for describing removing the check marker from a check box.
• Go to: Use for describing opening a menu, going to a tab or another particular place in the UI, or going to a web site.
• Enter: Use for describing entering a value into a UI element such as a text box or combo box.
• Move, drag: Use for describing moving anything from one place to another by dragging, cutting and pasting, or another method. Do not use “drag and drop”.
• Press: Use for describing pressing a keyboard key or a keyboard shortcut.
• Use: Use when select might be confusing. For example, “Use the arrow keys to navigate”.

Terms for UI Elements

• Dialog - not dialog box, pop-up, pop-up window.
• Checkbox - not check box.
• Dropdown list or dropdown menu - not dropdown or drop-down.

However, try to avoid talking about UI elements. Instead, describe what the user needs to do.

Qt-specific Terminology

For comprehensive Qt-specific terminology and concepts, refer to the Qt Terms and Concepts wiki page.

Avoid Ambiguity

Consider replacing ambiguous terms with specific ones, for example:

• Instead of “this”, specify what you’re referring to.
• Instead of “it”, repeat the noun or use a clear reference.
• Instead of “there are”, use a more direct construction.
• Instead of “enables”, use “allows” or “lets you”.

Formatting Conventions

Formatting Text Elements

• Monospace formatting: Use for file and folder names, file extensions, code, command-line commands, variable names.
• Bold formatting: Use for UI elements and keyboard shortcuts.
• Italic formatting: Use for emphasis.

Capitalization

Sentence case for most text, including:

• Regular sentences and paragraphs.
• List items.
• Table cells.

If it aligns with the documentation set, you can use Title case for headings (including table headers).

Numbers

• Spell out numbers one through nine.
• Use numerals for 10 and above.
• Always use numerals for:
  • Dimensions (5 pixels)
  • Version numbers (Qt 6.0)
  • Code-related values
• Use “more than” not “over” for quantities.
• Use “fewer” for countable items, “less” for uncountable.
• Use “later” and “earlier” when talking about versions. For example, “Qt 6.8 or later”.

Lists

• Use bulleted lists for unordered items.
• Use numbered lists for sequential items (like a step-by-step procedure) or prioritized items (like a top 10 list).
• Keep list items parallel in structure. Each list item should follow the same grammatical format, for example, start with a verb.
• End each item with a period if any item is a complete sentence.
• Introduce lists with a complete sentence ending in a colon.
• Don’t use semicolons, commas, or conjunctions (like and or or) at the end of list items.

Tables

• Use tables to structure more complex content into two or more rows (plus a header row) and two or more columns.
• Header row text should be bold.
• Don’t leave table cells empty, use “N/A”, “Not applicable”, or “None”.

Special Cases

Warnings and Notes

• Note: Additional helpful information.
• Warning: Critical information to prevent errors.

Use sparingly to maintain impact.

Cross-References

• Use “see” for direct references. For example, “For more information, see www.qt.io”.
• Use “see also” at the end of the topic or page for related topics.
• Avoid unnecessary in-sentence linking, especially in task topics and step-by-step procedures.
• Avoid “click here” or “this link”. Make sure the link text tells the user where the link takes them, especially for external links.

Common Advice

To avoid common mistakes, follow these rules:

• Don’t use “please” except in situations where the customer is asked to do something inconvenient or the application or site is to blame for the situation.
• Don’t use “simply” or “just” (implies task is trivial).
• Don’t use “obviously” or “clearly” (assumptions about reader knowledge).
• Don’t mix metaphors or use multiple metaphors.
• Don’t use exclamation points (except in congratulatory messages).
• Don’t use Latin abbreviations (use “for example” not “e.g.”).

Review Checklist

Before submitting documentation:

• [ ] Check (American English) spelling and grammar.
• [ ] Verify consistent terminology usage.
• [ ] Ensure active voice predominates.
• [ ] Confirm present tense for current behavior.
• [ ] Review pronouns for clear antecedents.
• [ ] Check that lists and tables are properly formatted.
• [ ] Ensure tone is professional yet approachable.
• [ ] Check that text is formatted correctly. For example, file names, code, UI controls, and so on.
• [ ] Images have descriptive alt texts.
• [ ] Links have descriptive texts.

Conclusion

Consistent writing style enhances the quality and usability of Qt documentation. These guidelines ensure that all Qt documentation maintains a professional, clear, and accessible standard that serves our global user community.

References

• Qt Terms and Concepts: https://wiki.qt.io/Qt_Terms_and_Concepts
• Microsoft Writing Style Guide: https://docs.microsoft.com/en-us/style-guide/