Content guidelines

Style guide

Q-CTRL adopts the Microsoft Style Guide for its completeness and relevance across mediums. The style guide is a set of rules and writing standards that ensure our audience recognizes our brand in various formats across all channels. In this section we highlight some of the most commonly used parts of the Microsoft Style Guide. Where the Microsoft Style Guide is unopinionated or Q-CTRL differs, these additions and exceptions are detailed below in the Tone and Voice sections of these content guidelines.

Math formulas

If your writing may be displayed in a terminal, such as a docstring, replace LaTeX formulas with plain text whenever possible. If you’re in the middle of a paragraph, spell out mathematical operations such as “plus”, “minus” or “times”. If you write the name of a fraction in the middle of a paragraph, include a hyphen in it (for example, “one-third”). When talking about two-dimensional and three-dimensional concepts, use the abbreviations “2D” and “3D” from the beginning.

Vocabulary choice

Write your text using the American English spelling. In particular, don’t use the following words, phrases, and spellings:

• Adapter: Replace it with “adaptor”.
• Administrate: Replace it with “administer”.
• Afterwards: Replace it with “afterward”.
• Alphabetic: Replace it with “alphabetical”.
• Alphanumerical: Replace it with “alphanumeric”.
• Appendixes: Replace it with “appendices”.
• Backend: Replace it with “back end”, two words.
• Back space: Replace it with “backspace”, a single word.
• Base line: Replace it with “baseline”, a single word.
• Bit map: Replace it with “bitmap”, a single word.
• Bolded: Replace it with “bold”.
• Boldface: Replace it with “bold”.
• Cancelled: Replace it with “canceled”.
• Cancelling: Replace it with “canceling”.
• Data base: Replace it with “database”, a single word.
• Frontend: Replace it with “front end”, two words.
• In-line: Replace it with “inline”, one word.
• Italics: Replace it with “italic”.
• Italicized: Replace it with “italic”.
• Lower case: Replace it with “lowercase”, one word.
• Matrixes: Replace it with “matrices”.
• Numerical: Replace it with “numeric”.
• Off-line: Replace it with “offline”, one word.
• On-line: Replace it with “online”, one word.
• Okay: Replace it with “OK”, capitalized.
• Timestamp: Replace it with “time stamp”, two words.
• Towards: Replace it with “toward”.
• Zeroes: Replace it with “zeros”.

Don’t use Latin words, expressions, and abbreviations (except for “etc.” and “vs.” or “versus”). In particular, don’t use:

• e.g.: Replace it with “for example”.
• i.e.: Replace it with “that is”.

Also don’t replace “and” with an ampersand (&) in text, and don’t replace the word “number” with the number sign (#).

Don’t use a hyphen (-) between a word and its prefix unless not doing so would create confusion. For example, use a hyphen in “non-native” and “pre-processing”, but in general avoid hyphens with the following prefixes: “anti-”, “auto-”, “bi-”, “co-”, “cyber-”, “exa-”, “giga-”, “kilo-”, “mega-”, “micro-”, “multi-”, “non-”, “pre-”, “re-”, “sub-”, “tera-”, and “un-”. Don’t add hyphens to avoid vowel collision, for example, write “reenter” and “cooperate”.

Don’t use directional terms such as “down”, “left”, “up”, and “right” to indicate parts of the documentation. Also, don’t use “above” and “below” to refer to parts of the documentation. You can use instead “previous”, “preceding”, and “earlier”, or “later” and “following”.

Use common acronyms. To form their plural, just add a lower-case letter “s” to the end of a singular acronym, but don’t modify it if it already stands for a plural word.

Text style

Be concise and precise in your text. Write short paragraphs that start with the most important information. Break down sentences that require more than a few commas into separate sentences, aiming for one verb per sentence. Keep adjectives and adverbs close to the words they modify to make sure there’s no ambiguity about which word or phrase they apply to. Don’t write long stacks of adjectives or adverbs, such as “extremely well thought-out”.

Replace paragraphs that are too complicated with lists, but don’t write instruction lists with more than seven steps.

To keep your text clear, don’t omit “that” and “who” when introducing subordinate clauses, and don’t omit the article “the” before nouns. Additionally, when using a word ending in “-ing”, make sure it’s clear whether it is a noun, an adjective, or a verb.

Be precise in your word choice. Use one word per concept, there’s no need to replace it with synonyms to avoid repetitions. Also avoid using two words when just one could be used, such as using a verb followed by a noun to represent something that can be expressed by just one common verb. In particular, avoid the following words and phrases with the following meanings:

• And/Or: Don’t use it if it can be replaced with “or”.
• And so on: Don’t use this, be specific or give an example instead.
• As well as: Don’t use it if it can be replaced with “and”.
• Alert: Don’t use it to mean “system message”.
• Alias: Don’t use it to mean account name or email address.
• Boot: Don’t use it to mean to “start up” a system.
• Different: Don’t use it to mean “various”.
• Either/Or: Don’t use it.
• Exit: Don’t use it to mean to “close” a program.
• Finalize: Don’t use it to mean “finish”.
• Illegal: Don’t use it to mean “invalid”.
• Initiate: Don’t use it to mean to “start” a program.
• Once: Don’t use it to mean “after”.
• Over: Don’t use it to mean “more than”.
• Quit: Don’t use it to mean “close” a program.
• Reboot: Don’t use it to mean “restart”.
• Roman: Don’t use it to mean “regular type”.
• Under: Don’t use it to mean “less than”.

Text formatting

Use sentence capitalization for headers and error messages. If hyphens are present, capitalize the same words that would be capitalized in a sentence if there were no hyphens. Capitalize the first word after a colon (:) in a header, but not in a sentence that is not a header, unless it is a proper noun or a direct quote.

Use a colon (:) to finish a sentence that introduces a list, and finish each item of an instruction list with a period (.). Write complete sentences for each step of an instruction list, and capitalize the first word of each sentence.

Always start a sentence with a word that can be capitalized, rewrite a sentence if its first word is always written in lower-case. If you’re not sure how a word is capitalized, check the American Heritage Dictionary. In particular, always use the following capitalization for the following words:

• Boolean: Always capitalize.
• cloud: Don’t capitalize if it’s not in the beginning of a sentence.
• DevOps: Use this exact spacing and capitalization.
• machine learning: Don’t capitalize if it’s not in the beginning of a sentence.
• open source: Don’t capitalize if it’s not in the beginning of a sentence.

To separate parenthetical sentences, use an emdash (—). Don’t add spaces before or after the emdash.