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.

# Tone

Q-CTRL’s tone changes depending on the audience and product we’re addressing.

# Q-CTRL: Our informational tone

Key elements: Knowledgeable, informative, instructive, confident.

Our goal is to demonstrate our mastery of quantum technology, our confidence in our product suite, and our ability to understand our customers. We offer useful and practical solutions for our users right now, and our tone always highlights practicality. We enable teams to embrace cutting-edge technology by simplifying complex problems into easy-to-understand concepts. We believe in being a catalyst for change, not just providing tools. Our Q-CTRL tone disseminates knowledge without dumbing it down.

# Black Opal: Our tutoring tone

Key elements: Relatable, engaging, accessible.

Our goal is to make quantum skills accessible to our customers and bring learning within reach. Black Opal’s warm and personal tone helps us connect with our audience. For example, we often use a conversational tone in our transactional emails to put customers at ease. We approach Black Opal copy with the voice of a tutor, instructing in real-time, making quantum technology accessible, never daunting or intimidating.

# Boulder Opal: Our academic tone

Key elements: Technical, analytical, formal.

Our goal is to inform and discuss, encouraging analysis and research. Boulder Opal’s users are advanced in their understanding of crucial quantum computing concepts and expect content that meets their level of competency. At the same time, even our technical tone shouldn’t veer too far into academic or abstract language, and we should keep jargon to a minimum.

# Fire Opal: Our technical tone

Key elements: Engaging, authoritative, confident.

Our goal is to demonstrate quantum expertise and knowledge that will build confidence in our software tools. We should disseminate concepts, information, and ideas as simply as possible within the boundaries of educational value; we should be careful not to sacrifice accessibility for technical detail. Fire Opal copy and content is more formal and technical than Black Opal but less technical than Boulder Opal.

# Voice

Tone and voice are two different things. The tone is how you sound when you speak. Voice is the words you use. Our overall voice remains consistent, regardless of our tone.

1. Clarity trumps everything. That’s why all copy should strip away all the distracting language and focus on:
   1. Engaging readers
   2. Informing readers
   3. Encouraging readers to take action
2. We’re experts at translating – explaining information without diluting it, removing jargon, and communicating with our readers in a way that is accessible without being simplistic.
3. We’re a people-powered company, and we understand our customers’ challenges and passion for technology. We speak to them in an equal, warm, and accessible way. When we encourage, we don’t use threatening language.
4. While we are happy to be down-to-earth, we avoid relying on wordplay, sloganeering or humor.

We are concise, clear-cut, and to the point. We are bold but never arrogant. We speak conversationally and respectfully. We are professional and passionate at the same time.

Simplicity is what drives our voice. It’s straightforward, empowering, and acknowledges how vital quantum technology is to our customers. They turn to us to achieve mission-critical, long-term strategic goals, and we want to give them the information they need without any fluff.

# Active voice

Use active voice. Avoid passive voice.

In active voice, the subject of the sentence performs the action. In passive voice, the subject of the sentence has the action done to it.

We want to engage our users, our customers and our audience, not put up abstraction barriers.

Active voice examples:

• Companies need quantum technology.
• The developer learned quantum skills.
• The team reached a crucial milestone.

Passive voice examples:

• Quantum technology is needed by companies.
• Quantum skills were learned by the developer.
• A crucial milestone was reached by the team.

Words like “was” and “by” may indicate that you’re writing in a passive voice. Scan for these words and rework sentences where they appear.

# We use all caps for our brand

Our brand name is a bold realization of our work and our vision. It should always be all caps:

Q-CTRL

# We use title case for our products and press releases

Black Opal
Fire Opal
Boulder Opal
Q-CTRL Embedded
Sensing

Q-CTRL Launches Black Opal Pro on World Quantum Day

Quantum computing and related concepts are features of our product and/or categories. They are not branded or proprietary to Q-CTRL so they should use sentence case.

# We use sentence case for our product features and components

Boulder Opal toolkits

# Presenting information

Someone reading technical content is usually looking to answer a specific question. Our goal is to provide answers without distraction.

Content should be as clear and concise as possible to help the reader find their answer quickly. If you have more than one answer, make sure they are well labelled and ordered, so they are easy to understand. Use images, diagrams, tables, graphs, and other visuals to illustrate your point or break up the text.

For each project, consider your reader’s background, context and objective.

When relevant, provide a brief outline of an article, email or landing page’s focus in an introductory paragraph or section, and stick to the topic at hand. Keep sentences, paragraphs, and procedural steps focused and concise.

Ask these questions:

• Is the reader a prospective user, a new user, or an experienced user?
• What is the goal of the user? To complete a task? To research a topic?
• Is the user in the middle of a task? Are they in a hurry? Could they be frustrated?

For all educational, contextual, and product documentation we have adopted the Diátaxis Framework which speaks to the intent of any document.

The Diátaxis Framework aims to solve the problem of structure in technical documentation. It adopts a systematic approach to understanding the needs of documentation users in their cycle of interaction with a product.

We don’t want to overload our audience with unnecessary information, choices, or complex ideas or phrases when we don’t have to. This is particularly critical when a user may be new and/or frustrated and when a user is experienced and time-poor.

# First, second, and third-person pronouns

As a general rule, we write in the first person plural - as Q-CTRL - when we create content. Put simply, Q-CTRL is always referring to ourselves as “We”; we are presenting content, we are discussing Black Opal, we are developing new technology.

A first-person plural narrative:

• Helps our readers to establish an immediate connection with our brand because our beliefs and emotions are not expressed through a third party (i.e., someone else).
• Allows our readers to quickly establish the nature of our brand’s relationships with our products and partners as they are described more directly than through a third party.

We write in the individual first person when the content is a blog post, research document or update that should be attributed to a specific person.

We write in the second person when we are expressing the value proposition of our products, platform, and research to our users. This includes our documentation.

# Footnotes and reference citations

When citing published content, follow the Physical Review Style and Notation Guide and include a link (preferably a DOI) where possible. For example:

C. D. B. Bentley, H. Ball, M. J. Biercuk, A. R. R. Carvalho, M. R. Hush, and H. J. Slatyer, Adv. Quantum Technol. 3, 2000044 (2020).
A. Waldron, P. Judd, and V. Miller, Physical Review Style and Notation Guide (American Physical Society, 2011), p. 5.