Product Documentation Style Guide

About this guide

This Style Guide provides editorial guidelines for text and media in Cotality product documentation and educational materials. The intent of these guidelines is to help maintain consistency in voice, content structure, and technical conventions used in Cotality product documentation. Content authors and editors should thoroughly review this guide to ensure we are creating high-quality, readable, and consistent materials across our product suite.

This guide is divided into five sections:

1. Style

2. Structure

3. Formatting

4. Classification of Documentation

5. Terminology

Style

The style guide supports our goal of providing quality product education for end-users, developers, and stakeholders.

When authoring or reviewing content, we strive to ensure that our documentation is:

• Comprehensive and written for all experience levels

• Technically detailed and accurate

• Practical, useful, and self-contained

• Friendly but formal

These principles guide authors and editors to create articles, tutorials, and other educational materials that help end-users, developers, and stakeholders get started and develop proficiency with our products. For conciseness, we will refer to our audience as “readers” throughout the remainder of this style guide.

Comprehensive and written for all experience levels

Our articles are written to be as clear and detailed as possible without making assumptions about the reader’s background knowledge or experience level. We aim to provide readers with the contextual and background information they need to understand core concepts while developing proficiency and expertise in the utilization of our products. Our product documentation should avoid unnecessary jargon, trendy constructions, vagueness, and buzzwords. We prioritize clarity and conciseness over lengthy paragraphs of unintelligible word salad.

Technically detailed and accurate

Our educational articles are technically accurate and follow industry best-practices. In general, we use U.S. English according to Merriam-Webster’s Collegiate Dictionary and the Chicago Manual of Style.

Our goal is to publish high-quality documentation that is easy to understand by the intended audience, whether they are end-users, developers, or other stakeholders, leading to increased satisfaction and reduced support costs. In our documentation, we strive for:

• Accuracy: This ensures that the information provided is correct and error-free. Accurate documentation prevents misunderstandings and mistakes that could arise from incorrect information. Accuracy is crucial because incorrect information can lead to product usage or implementation errors, potentially causing significant issues.

• Completeness: Comprehensive documentation covers all necessary aspects of the subject matter. It ensures that users have all the information they need without having to look elsewhere. Completeness is essential as it ensures that users do not miss critical information, which could lead to incomplete understanding or improper use of the product.

• Clarity: Clear documentation is easy to understand. It uses simple language, avoids jargon, and is well-organized, making it accessible to its intended audience. Clarity helps users understand the information without confusion, reducing the need for additional support.

• Consistency: Consistent documentation uses uniform terminology, style, and formatting throughout. This helps in maintaining a professional appearance and makes the document easier to follow. Consistency also provides a seamless reading experience, making it easier for users to follow and understand the documentation.

• Correctness: This involves ensuring that the documentation adheres to grammatical and syntactical rules. Correct documentation enhances readability and professionalism. Correctness also enhances the credibility and professionalism of the documentation.

• Usability: Usable documentation is user-friendly and easy to navigate. It includes features like a table of contents, index, and search functionality to help users find the information they need quickly. Usability ensures that users can efficiently find and use the information they need, improving their overall experience.

Content authors and editors should test their instructional materials by following them exactly as written to ensure accuracy and identify missing steps.

Practical, useful, and self-contained

Readers typically consult documentation when encountering issues while trying to perform a specific task. To that end, our documentation aims to provide solutions through step-by-step guidance. We avoid overly extensive documentation that may overwhelm users and make the product seem more complex than it is. Our product documentation guides readers to the most relevant information and helps them quickly grasp the product's key capabilities and functions.

To keep our articles short and concise, we are specific and focus on one problem per document. We include links to relevant articles and educational resources for mastery of additional concepts.

Friendly but formal

Our product documentation aims for a friendly but formal tone. This means that articles do not include jargon, memes, excessive slang, emoji, or jokes. We use an active voice in clear and concise language, avoiding unnecessary complexity and employing short sentences and simple words.

Text is written in second person and should speak to our readers directly using “you” and “your.”

The language of our documentation avoids offensive language or other content that is in reference to (but not limited to) age, disability, ethnicity, gender identity or expression, level of experience, nationality, neurodiversity, personal appearance, race, religion, political affiliation, sexual orientation, or socioeconomic status.

Structure

Most of the tutorials we publish are procedural and walk the reader through accomplishing a task step-by-step. The structure for a procedural article is as follows:

1. Article Title: How to [Task Name] with [Application] on [Platform]

2. Overview: A description of the task that your readers are trying to accomplish.

3. Media: Use visual elements like images, gifs, arcade click-throughs, and infographics to break up text, illustrate steps, and make the instructions more accessible.

4. Steps: Describe what the reader needs to do and why.

5. Outcome: What users can expect to happen after completing the steps in the how-to knowledge base article.

6. Further reading: Links to related knowledge base articles or how-to articles.

Other knowledge base articles may educate readers about a specific subject, rather than providing step-by-step instructions for troubleshooting. The structure for an informational article is as follows:

1. Article Title: [Software Platform, Application, or Feature Name]

2. Overview: A brief description of the product or feature the informational article is about.

3. Media: Use visual elements like images, videos, and infographics to illustrate key concepts, product features and benefits.

4. Features: What users can expect to achieve by using the key capabilities of the product.

5. Further reading: Links to related articles or other content around this specific product or feature.

Writing and editing tips

• When drafting an article overview, it’s important to think about the what and the why. Include what benefits the reader can expect to receive by learning about this topic or task. How will this make their work better?

• When drafting steps, be specific about what the reader is expected to do and why. Include tips and important information to keep in mind.

• It is important to include outcomes in our procedural articles to summarize what the reader will have accomplished when they’re done. What new skills will they have? What will they be able to do that they couldn’t do before? How will their work have changed?

• Keep the focus on the reader and what they will accomplish. Instead of using phrases like “we will learn how to,” use action-oriented phrases like “you will order” or “you will retrieve.” This takes the focus off of learning and puts it on doing, motivating the reader and getting them excited about the topic.

• Informational articles and media should keep the focus on the problem the technology is solving rather than the intricate details of the technology itself. Include what the software does to solve a customer pain point. Details about how the technology works should live in the procedural articles and media.

• Our product documentation is written from a user perspective. We focus on the functionality and benefits that the product brings to user, rather than what Cotality has created.

  • Avoid verbs like “allow” and “enable” (which indicate the focus is on the product design) and instead write from a user perspective.

  • Correct: You can access comprehensive credit reports directly within your workflow.

  • Incorrect: Credco enables users to access comprehensive credit reports directly within their workflow.

• Product documentation should be focused on providing clear, concise information, without the addition of sales or marketing text.

  • Do not use words like easily or simply.

  • Do not use marketing phrases like, “This feature will save you time and money.”

• Avoid writing about the document itself. Instead of using phrases like, “this page shows” or “this article explains,” focus on the user and the actions they can take with the product.

  • Correct: You can submit an Income Analysis order via Encompass® Desktop, Encompass® Web, or the AutomatIQ® Borrower Portal.

  • Incorrect: The purpose of this article is to describe how to submit an Income Analysis order via Encompass® Desktop, Encompass® Web, or the AutomatIQ® Borrower Portal.

Formatting

Landing pages

• The product landing page should follow the standardized template.

• Avoid the use of the gerung (verbs ending in -ing) in category titles.

• Do not display more than 6 articles per category. For categories with more than 6 articles, create a subcategory landing page and link to it.

Article titles, headings, and subheadings

• We use task-based titles in our procedural documentation.

• Article titles should be written in title case.

• Article headings and subheadings should be written in sentence case.

• We do not use terminal punctuation unless a question mark is required.

• Article titles do not use the serial comma.

  • Ex: subject, subject and subject

• Article titles use the ampersand (&) in place of “and.”

• Article headings and subheadings use the serial comma.

  • Ex: subject, subject, and subject

• Article headings and subheadings use the word “and.”

• Article title should be set to H1.

• Article headings should be set to H2.

• Article subheadings should be set to H3.

• Article overviews, steps, outcomes, features, and further reading are headings and should be set to H2.

• All other categories should be subheadings set to H3.

• Avoid the use of H4.

• Media content should NOT have a subheading.

Article overviews

• “Overview” subheading should be set to H2.

• Article overviews should be written in sentence case.

• Article overviews should use terminal punctuation.

• Paragraphs should be no more than 5 sentences.

General formatting guidelines

• We adhere to the Cotality branding guidelines and resources located here.

  • Exception: TWK Everett and Inter are not supported system fonts, so we use Poppins as the standard font throughout our documentation.

• Key terms and UI elements should be capitalized in bold.

  • Do not bold commands.

• Do not bold the colon following bold text.

  • Correct:

  • Incorrect:

• UI elements should be written in title case.

• The word “button” should be in sentence case and not bolded.

• Field entries should be placed in quotation marks and should not be bolded. Example:

  • Type “your name” in the Name field.

• Standard font size for text is 16.

• Our standard font color is black. We do not change the color of headers, subheadings, or text to colors other than black.

• Avoid overusing italics for emphasis as it can hinder readability. Only technical terms should be in italics.

• Acronyms should be spelled out in their first use with the abbreviation in parenthesis. Example:

  • AutomatIQ Borrower® (AIQB)

• Spell out whole numbers from zero through one hundred. (Excluding steps.)

• Use numbers for 101 and above.

• Product names should be capitalized throughout our documentation.

• Copyrights and trademarks should accompany product names where applicable. Refer to the Cotality website for guidance.

• Circumstances or conditions should precede an action. (i.e. to accomplish y, do x.) Mentioning the circumstance first lets the reader skip the instruction if it doesn't apply. Examples:

  • For more information, see [link to other document].

  • To delete the entire document, click Delete.

• Bullets and steps should have more than one accompanying bullet or step and should not stand alone in an article. (Bullet 1 or Step 1 should be followed by Bullet 2 or Step 2.)

• Bullet points should use terminal punctuation for consistency.

• Do not use bullets under steps. Use callouts to call attention to tips, notes and warnings.

• Main sections should be separated by a solid divider line.

• Subsections should be separated by a single space.

Media

Steps

• The steps subheading should be set to H2.

• The steps subheading should appear above the media.

• Steps subheading describes the action of the procedure (Ordering [insert product name])

• Steps in procedural articles should use terminal punctuation.

• Primary steps should appear in a numbered list.

• A step should include the step number (numerical) followed by a decimal. Example:

1. Select the Order Report button.

2. Click the Submit button to open the next screen.

• Nested steps should be indented once from the primary step and use a lowercase letter (a, b, c, etc). Example:

1. Navigate to the Service Provider Detail section.

a. Enter “CoreLogic” in the text field.

• Second-level nested steps should be indented once from the first nested step and use a lowercase Roman numerals (i, ii, iii, etc). Example:

1. Navigate to the Service Provider Detail section.

a. Enter “CoreLogic” in the text field.

i. Enter your nested content.

Snippets and reusable content

Tip callouts

Purpose: To provide optional but helpful advice, shortcuts, or alternative methods that can make the user's task easier or more efficient. A tip is a "nice-to-know" that isn't critical for success.

Guidelines

• Use for non-essential information that adds value.

• Keep the text concise and actionable.

• Ensure the tip is directly related to the preceding content.

Example:

Tip: Press Ctrl + F (or Cmd + F on Mac) to quickly search for a specific keyword on the page.

Instructions

1. Type /snippets and press Enter.

2. Turn on Insert Local Copy.

3. Select Tip Callout.

Note callouts

Purpose: To provide supplementary information, context, or clarification that the user needs to understand a concept fully. A note is important for comprehension but isn't a procedural step itself.

Guidelines

• Use to explain a "why" or provide background details.

• Use to define a term or explain a system's behavior.

• If the information is a required action, it belongs in the main body text, not in a Note.

Example:

Note: The system automatically saves your draft every two minutes. A "Draft saved" confirmation will appear at the top of the screen.

Instructions

1. Type “/snippets” and press Enter.

2. Turn on Insert Local Copy.

3. Select Note Callout.

Warning callouts

Purpose: To alert the user to a critical piece of information that, if ignored, could result in errors, data loss, security risks, or other negative consequences. Warnings should be used to prevent irreversible actions.

Guidelines

• Use sparingly. Overuse will diminish their impact.

• Clearly state the action the user should be cautious about.

• Explain the potential negative consequences if the warning is ignored.

• If possible, instruct the user on how to avoid the negative outcome.

Example:

Warning: Deleting a project is permanent and cannot be undone. All associated files will be permanently lost.

Instructions

1. Type /snippets and press Enter.

2. Turn on Insert Local Copy.

3. Select Warning Callout.

Multiple bullets inside of callouts

Multiple notes, tips, or warnings inside of a callout should be separated by bullets. Change the callout text from singular to plural and use bullets as illustrated below:

Notes

• This is a note bullet.

• This is a second note bullet.

Buttons

Purpose: To provide a link to another page or site. Should be primarily used on Product Landing Pages

Example:

See all articles

Instructions

1. Type /snippets and press Enter.

2. Turn on Insert Local Copy.

3. Select See all articles button.

Accordions

Purpose: Accordions (also known as "expand/collapse" or "dropdowns") are used to group and hide content under a title. This helps reduce the initial amount of information on a page, making it less overwhelming and easier to scan. They are ideal for progressively disclosing information that isn't relevant to every user.

Guidelines

• When to use:

  • FAQs: Perfect for lists of questions and answers.

  • Secondary information: For content like "Advanced Settings," "Optional Fields," or "Troubleshooting Steps" that supplement the primary topic.

  • Long lists: To condense long, scannable lists (e.g., definitions, version release notes).

• When NOT to use:

  • Do not place critical information that the majority of users need to see inside an accordion. Core instructions and essential warnings should always be visible.

• Accordion titles:

  • The title must be a clear and concise summary of the content within. Users should know exactly what to expect before they click.

  • Use a direct question (for FAQs) or a noun phrase (for topics).

  • Good title: How do I add a team member?

  • Good title: Advanced Export Options

  • Bad title: Click Here for More

Tables

Purpose: Tables are used to present structured data in a grid of rows and columns, making it easy for users to scan and compare information. Use tables when data has a clear and logical relationship that is best understood visually.

Guidelines

• Comparing Data: Showing the differences between two or more items (e.g., product features).

• Presenting Specifications: Listing technical requirements, settings, or parameters (e.g., image dimensions, command-line options).

• Defining Terms or Scenarios: Organizing sets of related items, such as "if-then" conditions or cause-and-effect relationships.

Structure:

• Every table must have a clear, descriptive title or caption above it that explains its contents (e.g., "Table 1: User Role Permissions").

• All columns must have a header that clearly labels the data within that column.

• Avoid overly complex tables with merged cells or nested tables. If a table becomes too complicated, consider splitting it into multiple, simpler tables.

Formatting:

• Table Title should be set to H3.

• Table Headers should use Title Case and be shaded #F2F2F2

• Table Cells should use Sentence case. Do not use title case for regular cell content.

• Text should be left-aligned.

Examples:

Acceptable OCR Forms and Documents

Product Comparison Matrix

Classification of Documentation

Our product documentation adheres to our enterprise-wide policy covering classifying and handing information, located here.

In accordance with this policy governing the classification of public, internal, and confidential information, the person or group most knowledgeable of the data contained in our documentation determines the classification of individual documents.

Given that our product documentation center handles mixed types of information, individual documents are secured separately according to their different classifications.

Questions about this policy should be directed to the legal and compliance group.

Terminology

This word list covers style and usage guidelines that are specific to product documentation.

If the term that you're looking for isn't on this list, refer to our preferred dictionary, Merriam-Webster.

Numbers and Symbols

& (ampersand)

Don't use & instead of “and” in headings, text, navigation, or tables of contents.

It's OK to use & when referencing UI elements that use &, or in table headings and diagram labels where space constraints require abbreviation.

A

access (verb)

Avoid when you can. Instead, use friendlier words like see, edit, find, use, or view.

access token

Lowercase except at the beginning of a sentence, heading, or list item.

account name

Don't use. Instead, use username.

address bar

Use to refer to the URL bar or the combined URL bar and search box in a browser.

ad hoc

OK to use in database and analytics contexts to mean "free-form" or "user-written" (for example, ad hoc queries or an ad hoc chart). For other contexts, try to find a more specific English equivalent.

Don't hyphenate or italicize the term.

admin

Write out administrator unless it's the name of a UI label or other element.

AI

In general, you can use AI without spelling out artificial intelligence.

aka

Don't use. Instead, write out also known as, or present an alternative term using parentheses or the word or. You can also write out a definition.

allows you to

Don't use. Instead, use lets you.

Alpha

Lowercase except when part of a product name.

America, American

Use only to refer to the Americas or the American continent.

Don't use to refer to the United States. Instead, use a more precise term like the US or the United States, and people in the US.

AM, PM

Use all caps, no periods, and a space before.

• Example: 9:00 AM

and/or

Don't use unless space is limited, such as in a table.

API

Use API to refer to either a web API or a language-specific API.

Don't use API when referring to a method or a class.

API key

Not developer key or dev key.

app

In general, use app instead of application when referring to programs for end users, especially in the context of mobile or web software.

In some contexts, such as enterprise software, it's OK to use application to convey a sense of greater complexity.

Use application in standard phrases such as application programming interface.

appendix

Use the plural appendixes, not appendices.

as

If you mean because, then use because instead of as. As is ambiguous; it can refer to the passage of time. Because refers to causation or the reason for something.

as of this writing

Avoid because this phrase is implied. The phrase can also prematurely disclose product or feature strategy or inappropriately imply that a product or feature might change.

authentication and authorization

In general, use the word authenticated only to refer to users, and use authorized only to refer to requests that are sent by a client app on behalf of an authenticated user.

auto populate

Not auto-populate.

auto scaling

Not auto-scaling.

auto tagging

Not auto-tagging.

B

backend

Not back-end or back end.

below

Don't use to refer to a position in a document. Instead, use later or following.

beta

Lowercase except when part of a product name.

between versus among

It's fine to use between when talking about more than two things; however, between isn't interchangeable with among.

Use between when you're talking about two or more distinct things.

billing charges

Don't use billing charges to mean charges that appear on a bill. Instead, use billed charges.

boolean

In most contexts, boolean refers to a specific data type in a specific programming language. In such cases, use code font and the exact spelling and capitalization of the programming keyword.

button

In a UI, a link isn't the same as a button; don't use the term button to refer to a link.

C

cell phone, cellphone

Don't use. Instead, use mobile device.

cellular data

Don't use. Instead, use mobile data.

cellular network

Don't use. Instead, use mobile network.

chapter

When referring to documentation that isn't in the form of a book, don't use the term chapter. Instead, refer to documents, pages, or sections.

check

Don't use to refer to marking a checkbox. Instead, use select.

checkbox

Not check box.

choose

Choose is fine to use for generic contexts. For UI elements, use select.

clear

Use as a verb to refer to clearing a check mark from a checkbox.

click

When the environment is a desktop with a mouse, use click for most targets, such as buttons, links, list items, and radio buttons. Don't use click on.

click here

Don't use. Avoid vague link text.

clickthrough

Use as a noun.

click through

Use as a verb.

client secret

Lowercase except at the beginning of a sentence, heading, or list item.

codebase

Not code base.

codelab

Not code lab or code-lab.

compliant, compliance

Use with caution. A claim that a product or its output is compliant with a standard is a strong statement.

comprise

Don't use. Instead, use consist of, contain, or include.

config

Avoid when possible. Instead, spell out the full word when it's used in a non-code sense: configuration or configuring

confidential

Confidential data is data that is protected to prevent unauthorized access.

cons

Don't use. Instead, use a more precise term, such as disadvantages.

copy and paste

Avoid using. Instead, explain what to enter into a field and not how.

could

Avoid using. Instead, use can where possible.

CPU

All caps. No need to expand the abbreviation on first mention.

Create a new ...

Avoid using unless you need to distinguish the item from another recently created item. Instead, use Create a ... (e.g., Create a project, not Create a new project).

currently

Avoid because this word is implied. The word can also prematurely disclose product or feature strategy or inappropriately imply that a product or feature might change.

D

dash

Do not use to refer to a hyphen.

dashboard

Should not be capitalized unless it is part of a product name.

data center

Not datacenter.

data source

Not datasource.

data type

Not datatype.

deprecate

To deprecate an item is to recommend against the item's use, typically as a warning that the item will soon be unavailable or unsupported. Don't use deprecated to mean removed, deleted, shut down, or turned down.

deselect

Don't use to refer to clearing a check mark from a checkbox. Instead, use clear.

desire, desired

Don't use. Instead, use a word like want or need.

dialog

Use dialog for the UI element sometimes called a dialog box.

Use dialogue only for verbal interaction between people.

disable

Don't use disable or disabled to describe something that's broken.

When describing a user action or the state of a UI element, use a more precise term where possible. You can use inactive, unavailable, deactivate, turn off, or deselect, depending on the context. Use the same term consistently throughout your document

DNSKEY

One word, all capital letters.

documentation or document or documents

To refer specifically to the text on a page that explains a product, feature, or service, use this document, and not this article, this topic, this doc, or this page. It's OK to use this tutorial, this quickstart, or this codelab for those specific documentation types.

Always spell out documentation except in cases where space is limited, such as in tabs and URLs.

documentation set

Not doc set or docset.

does not yet

Avoid in timeless documentation because this phrase can become outdated. The phrase can also prematurely disclose product or feature strategy or inappropriately imply that a product or feature might change.

double-tap

Hyphenate. Lowercase except at the beginning of a sentence, heading, or list item.

downscope

Consider using a more descriptive term like constrain scope or reduce scope. Because downscope might not be broadly understood, if you use the term, make sure to define it on first use.

drag

Use drag, not click and drag and not drag and drop.

drop-down

In most cases, you can omit drop-down from phrases like drop-down list or drop-down menu, and just use list or menu. Include drop-down as a modifier only if the omission would cause ambiguity. Don't use drop-down as a standalone noun.

dumb down

Don't use. Instead, use a word or phrase what's happening, such as simplify or remove technical jargon.

dummy variable

Don't use to refer to placeholders. Instead, use placeholder.

E

each

Each refers to every individual item taken individually, not to a group of items taken collectively.

earlier

Use for a range of version numbers, not lower. When referring to a position in a document, use earlier or preceding, not higher.

easy, easily

What might be easy for you might not be easy for others. Try eliminating this word from the sentence because usually the same meaning can be conveyed without it.

ecommerce

Not e-commerce.

e.g.

Don't use. Instead, use phrases like for example or such as. Many people confuse e.g. and i.e.

egress

When referring to the networking term, use lowercase.

either

In general, use either only for a choice between two things, not for a choice among multiple things.

eLearning

Not e-learning or elearning.

element

In HTML and XML, a tag is a component of an element that indicates the start or end of the element. In general, don't use the term tag to refer to an entire element.

email

Not e-mail, Email, or E-mail. Don't use as a verb.

emoji

Use emoji for both singular and plural forms.

enable

In procedures, use the appropriate label and action for the UI element that the user interacts with. When describing a user action or the state of a UI element, use a more precise term where possible. It's OK to use enable when not referring to a person.

endpoint

Not end point.

enter

Use enter to refer to the user entering text.

error-prone

Hyphenate. Lowercase except at the beginning of a sentence, heading, or list item.

etc.

Avoid using etc., and so forth, and and so on wherever possible. If you really need to use one, use etc. Always include the period, even if a comma follows immediately after.

eventually

Avoid in timeless documentation because this word can become outdated. The word can also prematurely disclose product or feature strategy or inappropriately imply that a product or feature might change.

execute

Verb commonly used to refer to function calls, SQL queries, and other processes. When the meaning is the same, use the simpler word run instead. If you need to use a more precise term for your context, use that term.

expander arrow

The UI element used to expand or collapse a section of navigation or content. If you describe this element, use the terms expander arrow and expandable section

exploit

Don't use exploit to mean "use."

Only use exploit in the negative sense, such as to describe exploiting a security vulnerability.

external VPN gateway

Write external and gateway all lowercase except at the beginning of a sentence, heading or list item.

extract

Use instead of unarchive or uncompress.

F

fat

Don't use. Instead, use a precise modifier that conveys the appropriate meaning.

filename

Not file name.

file system

Not filesystem.

fill in; fill out

Use fill in when referring to entering information in individual fields.

Use fill out when referring to completing an entire form.

final solution

Don't use. Instead, use solution as a standalone term or, depending on the context, definitive, optimal, best, or last solution.

fintech

Write out on first mention: financial technology (fintech). Don't use FinTech or fin-tech.

firewalls

Don't use in Compute Engine or networking documentation. Instead, use firewall rules.

following

It's not necessary to use a noun after following unless it helps provide clarity and enables accessibility.

foo

Avoid when possible even though it's a common term in the developer community. Instead, use a clearer and more meaningful placeholder name.

for instance

Avoid when possible. Instead, use for example or such as.

frontend

Not front-end or front end.

functionality

Use with caution. With respect to hardware or software, functionality refers to a set of associated functions or capabilities and how they work. However, the word is sometimes overused, especially when the intended meaning is capabilities or features.

future, in the future

Avoid in timeless documentation because this word or phrase can become outdated.

G

GBps

Short for gigabytes per second. By convention, we don't use GB/s.

Gbps

Short for gigabits per second. By convention, we don't use Gb/s.

gender-neutral he, him, or his (or she or her)

Don't use. Instead, use the singular they. Don't use he/she or (s)he or other such punctuational approaches.

generative AI

Spell out generative. Use sentence case.

Don't use gen AI or Gen AI. Don't hyphenate.

ghetto

Don't use. Instead use more precise terms like clumsy, workaround, or inelegant to refer to code that isn't in a production-ready state.

gimp, gimpy

Don't use. Instead, use precise, non-figurative language to refer to a deficiency in a component.

Google, Googling

Don't use as a verb or gerund. Instead, use search with Google.

grandfathered

Don't use to refer to something that is allowed to violate a rule because it predates the rule. Instead, use an adjective like legacy or exempt or a verb like made an exception.

gray-box, grey box

Avoid using gray-box, graybox, or gray box to describe testing.

To refer to testing that's a combination of clear and opaque testing methods, describe exactly what it's doing.

grayed-out, greyed-out, gray out, grey out

Don't use. Instead, use unavailable.

guru

If possible, use a more precise term. For example, if you mean expert or teacher, use those terms.

guys, you guys

When referring to a group of people use non-gendered language, such as everyone or folks.

gypsy

Don't use. To refer to the people, use Romani, Roma, or Traveller, as appropriate for the specific group you're referring to. In place of metaphorical uses of the term, use more precise phrases.

H

hamburger, hamburger menu

Don't use. Instead use the aria-label for that particular icon.

hands off, hands-off

Use a less figurative phrase, such as automated.

hands on, hands-on

Use a less figurative phrase, such as customizable

hang, hung

Don't use to refer to a computer or system that is not responding. Instead, use stop responding or not responding.

happiness and satisfaction

Use happiness when referring to a customer's perception of a site's reliability. Use satisfaction when referring to whether the site meets the customer's needs.

hardcode

Use as a verb.

hardcoded

Use as an adjective.

he, him, his

Don't use a gendered pronoun except for a specific individual of known gender. Use they and their for the general singular pronoun.

healthcare

Not health care or health-care.

health check

Use with caution. When describing an action taken for a computer system, only use the term health check if this is the term that appears in the interface. Be certain to remove any ambiguity regarding whether the term refers to health in the medical sense.

healthy

Don't use

high availability

Use as a noun.

high-availability

Use as an adjective.

higher

Don't use for a range of version numbers. Instead, use later.

Don't use to refer to a position in a document. Use earlier or preceding.

Don't use to refer to a position in the UI. Instead, write instructions that avoid directional language.

high performance computing (HPC)

Don't hyphenate. Lowercase except at the beginning of a sentence, heading, or list item.

hold the point over

Do not use. Use point to.

holiday, the holidays

Don't use to refer to the end of the year. Instead, refer to specific quarters or months.

home screen

Not homescreen or home-screen.

hostname

Not host name.

hot

Avoid when possible.

hotspot

In databases, hotspots occur when a small number of nearby rows are accessed frequently in a short period of time, causing CPU spikes and affecting performance. Use hotspot and hotspots as nouns. Don't use verb and gerund forms such as hotspotting, because they translate less consistently.

housekeeping, house keeping, house-keeping

Don't use. Instead, use less figurative and more precise terms, such as maintenance and cleanup.

hover over

Ok to use when describing a mouse action.

HTTPS

Not HTTPs.

I

ID

Not Id or id, except in string literals or enums.

In some contexts, it's best to spell out as identifier or identification.

i.e.

Don't use. Instead, use phrases like that is. Many people confuse e.g. and i.e.

if

Although it is common in casual usage to omit the word then in if...then statements, you should include helper words like then in technical documentation.

image

Image by itself doesn't localize well because of its many meanings. Consider adding context—for example, disk image or container image.

impact

Use only as a noun. Instead of writing that something has an impact, use the word affect.

index

Use the plural indexes unless there is a domain-specific reason (for example, a mathematical or financial context) to use indices.

ingest

Use import, load, or copy when referring to simple movement of data. Use ingest only when referring to such operations that also involve significant processing of the data.

ingress

Use import, load, or copy when referring to simple movement of data. Use ingest only when referring to such operations that also involve significant processing of the data.

in order to

Avoid in order to; instead, use to.

Use in order to when needed to clarify meaning or to make something easier to read.

inline

One word as an adjective, inline, not in line or in-line.

instance group

Don't abbreviate to IG.

intercluster

Use unhyphenated intercluster, not inter-cluster.

interconnectAttachment

Use when referring to the API.

Interconnect type

Don't use. Instead, use connection type.

interface

OK to use as a noun.

Don't use as a verb. Instead, use interact, talk, speak, communicate, or other similar terms.

internal DNS

Write internal all lowercase except at the beginning of a sentence, heading, or list item.

internet

Lowercase except at the beginning of a sentence, heading, or list item.

Internet Key Exchange (IKE)

Write out and capitalize each word on first use. OK to abbreviate IKE after first use.

IoT

OK to use as an abbreviation for Internet of Things. Note the lowercase o.

IPSec

Not IPSec or IPSECShort.

Short for Internet Protocol Security.

J

janky

Use only to refer to a glitch or problem with graphics that is caused by a loss of data or inadequate refresh rate. Don't use otherwise. Use a less figurative term to refer to something of poor or unreliable quality.

just

Avoid. Usually, just is a filler word that you can delete without affecting your meaning.

K

KBps

Short for kilobytes per second. By convention, we don't use KB/s.

Kbps

Short for kilobits per second. By convention, we don't use Kb/s.

kebab, kabob, kebab menu, kabob menu

Don't use. Instead use the aria-label for that particular icon.

key

Don't use as an adjective in the sense of crucial or important.

If you use key as a noun, specify which kind of key you're referring to on first mention, because there are many kinds of keys in technical contexts.

key pair

A pair of keys, such as a public key and a private key. Contrast with key-value pair, which refers to a pairing that specifies a value for a variable (as in configuration files).

key ring

Use instead of keyring (without the space) when referring to a grouping of Cloud KMS keys.

key-value pair

Use instead of key/value pair or key value pair.

kill

Avoid when possible. Instead, use words like stop, exit, cancel, or end.

L

lame

Don't use. Instead, use precise, non-figurative language to refer to a deficiency in a component.

later

Use for a range of version numbers, not higher.

latest

Avoid in timeless documentation because this word can become outdated.

learnings

Don't use. Instead, refer to knowledge or things that you learned.

left-nav, right-nav

Don't use directional language. If referring to navigational elements for documentation, use content navigation menu.

legacy

If possible, use a more precise term. If you do use legacy, include or point to a definition to clarify what you mean in the current context. Don't use legacy with any sort of pejorative connotation.

let’s

Don't use if at all possible.

leverage

Avoid using if you mean use. If possible, use a more precise term. For example, use, build on, or take advantage of.

lifecycle

Not life cycle or life-cycle.

like versus such as

It's OK to use either like or such as for comparisons or examples.

limits

In an API context, limit often refers to usage limits (number of queries allowed per second or per day). Where possible, specify the kind of limit that you mean, such as usage limit or service limit; the word limit can refer to many different kinds of limits, including rules about acceptable use.

lint

Write both command-line tool name and command in lowercase. Use code font except where inappropriate.

livestream

Not live stream.

load balancing

Use as a noun.

load-balancing

Use as an adjective.

lock screen

Not lockscreen or lock-screen.

login

Use as a noun or adjective.

log in

Use as a verb.

long press

don't use. Instead, use touch and hold.

long-running operation

Not long running operation.

lower

Don't use for a range of version numbers. Instead, use earlier.

Don't use to refer to a position in a document. Instead, use later or following.

Don't use to refer to a position in the UI. Instead, write instructions that avoid directional language.

M

male adapter

Don't use. Instead, use a genderless word like plug.

man hours, manhours, man-hours

Avoid using gendered terms. Instead use terms like person hours.

man-in-the-middle (MITM)

Avoid using gendered terms. Instead use person-in-the-middle (PITM).

manmade, man made

Avoid using gendered terms. Instead use a word like artificial, manufactured, or synthetic.

manned

Avoid using gendered terms. Instead use terms like staffed or crewed.

manpower, man power, man-power

Avoid using gendered terms. Instead use terms like staff or workforce.

Markdown

Always capitalized, even when you're referring to a nonstandard version.

master

Use with caution. Where possible, replace master with a specific term that is accurate for the context, such as primary, main, original, parent, initiator, driver, controller, manager, mixer, aggregator, publisher, leader, or active.

Material Design

Capitalize each word in Material Design.

matrix

Use the plural matrixes unless there is a domain-specific reason (for example, a mathematical context) to use matrices.

may

In general, reserve for official policy or legal considerations.

To convey possibility, use can or might instead.

To convey permission, use can instead.

MBps

Short for megabytes per second. By convention, we don't use MB/s.

Mbps

Short for megabits per second. By convention, we don't use Mb/s.

media type

In general, use the term media type. In contexts where you need to refer to a content type—For example, if you mention the Content-Type HTTP header—it's okay to use content type instead, to avoid confusion. Don't use MIME type.

metafeed

Not meta-feed.

metageneration

Not meta-generation.

method

In programming contexts where method refers to a member of a class (as in Java), avoid also using the word generically to mean "approach" or "manner."

metropolitan area (metro)

In networking, a metro is a city where a colocation facility is located.

microservices

Not Microservices or micro-services.

might

Use to convey possibility or an uncertain outcome (for example, "You might be prompted to enter your credentials").

mobile

Don't use mobile as a standalone noun. Instead, specify mobile phone, or if you're talking about more than phones, then use mobile device.

mobile data

Use instead of cellular data.

mobile device

Use mobile device when you're referring to more than phones (for example, tablets and phones).

mobile network

Use instead of cellular network.

mobile phone

If you're talking about more than phones, then use mobile device. It's OK to use phone (without mobile) when the context is clear.

multi-cluster

Hyphenate.

multi-region, multi-regional

Hyphenate when referring to a ocation that consists of more than one region.

multi-service

Hyphenate.

multi-tenancy

Hyphenate.

must

Use to describe a required action or state (for example, "You must have the Editor role"). You can also write you need in order to convey a requirement.

N

N/A

Not NA.

native

Avoid using native to refer to people.

When referring to software products, try to use a more precise term—for example, use built-in to describe a feature that's part of a product.

navigation bar

Don't use to refer to a navigation menu.

new, newer

Avoid in timeless documentation because this word can become outdated.

New also implies that the reader knows the older product and that labeling something as new is therefore meaningful.

ninja

Don't use to refer to a person. Instead, use a term such as expert.

now

Avoid when describing features of products or services because this word is implied.

O

off-the-shelf

Use more widely understood terms like ready-made, prebuilt, standard, or default.

old, older

Don't use to refer to a previous version of a product. Instead, use earlier.

omnibox

Don't use. Instead, use address bar.

once

If you mean after, then use after instead of once.

on-premises

Not on prem, on premise, or on-premise. Hyphenate when used as any part of speech.

OS

OK to use as a shortening of "operating system."

outpost

Don't use. Instead, use channel.

P

path

Avoid using filepath, file path, pathname, or path name if possible.

peer gateway

Don't use on-premises gateway when you mean a peer gateway. A peer gateway can be an on-premises device or service or another cloud gateway.

peer network

Don't use on-premises network when you mean a peer network. A peer network can be an on-premises network or another cloud network.

per

To express a rate, use per instead of the division slash (/), unless space constraints require the use of the slash.

performant

Avoid where possible. Instead, use a more precise term.

persist

Don't use as a transitive verb. It's best to avoid using as a verb at all, especially in passive voice.

personally identifiable information (PII)

Some government agencies use the less common term personally identifying information; use this alternate term only in contexts where you're referring to a document that uses this term.

plain text

In most contexts, use plain text, but use plaintext in a cryptography context.

please

Don't use please in the normal course of explaining how to use a product, even if you're explaining a difficult task.

Don't use the phrase please note.

plugin (noun), plug-in (adjective), plug in (verb)

PM

Use all caps, no periods, and a space before.

• Example: 9:00 PM

point to

Use to refer to the action of pointing the mouse pointer (focus). This action doesn't imply a length of time waiting for the UI to react to user action.

pop-up, popup

Don't use.

To describe a window that appears and asks for, or presents, additional information, use dialog.

populate

OK to use if you're writing about a process populating a table or other entity. If you're writing about a person, use fill in.

port

Use listen on (not to).

possible

Don't use possible or impossible to mean you can or you can't.

postmortem

Avoid in general usage. Instead, use retrospective.

practitioner

Avoid using without any supporting information to define the roles that you're referring to.

prebuilt

Not pre-built.

pre-existing

Not preexisting.

prerecorded

Not pre-recorded.

pre-shared key

Not preshared key.

presently, at present

Avoid because this word or phrase is implied. The word or phrase can also prematurely disclose product or feature strategy or inappropriately imply that a product or feature might change.

press

Use when referring to pressing a key or a key combination to cause an action to occur. Also use for mechanical buttons.

For on-screen and soft (capacitive) buttons, use tap.

presubmit

Not pre-submit.

primitive

Use with caution. Don't use primitive in a disparaging sense.

project

In Google Cloud documentation, use Google Cloud project on first mention and in any context in which there might be ambiguity about what kind of project you're referring to.

pros

Don't use. Instead, use a more precise term, such as advantages.

Q

quick, quickly

What might be quick for you might not be quick for others. Try eliminating this word from the sentence because usually the same meaning can be conveyed without it.

quota

In API contexts, often refers to API usage limits. Where possible, it's best to use a more specific term, such as usage limit; the word quota means many different things to many different people.

R

read-only

Not read only. Always hyphenate read-only.

redline

Don't use as a verb. Instead, use precise terms appropriate to the context.

In the context of editing or providing a review, refer to those actions or to tracking changes.

regex

Don't use. Instead, use regular expression.

repo

Don't use. Instead, use repository.

review

If you mean "read, potentially for the first time," then use read instead of review.

If you mean "read critically, commenting on problems" (as in code review), then review is fine.

roll out

Don't use to mean a sudden or instantaneous launch. If you use roll out, define what you mean. When possible, use a more precise, non-figurative term like gradual, in stages, phases, or progressive.

runbook

Not run book.

runtime, run time

Use the noun runtime when referring to the environment in which software runs, such as a Ruby or Java runtime.

Use the noun phrase run time when referring to the time during program execution when something occurs

S

SaaS

Write out on first mention: software as a service (SaaS).

sane

Don't use. Instead use a word like valid or sensible.

sanity check

Don't use. Instead, use a term like quick check, confidence check, preliminary check or coherence check.

scale

Don't use scale alone to say that something is large or increasing.

screenshot

Use as a noun.

scroll

OK to use scroll as a verb, but if possible, instead use a term that isn't specific to implementation. For example, write go to the section, instead of scroll to the section.

select

Use to describe choosing an item from among multiple options, selecting text, or marking a checkbox.

sensitive

Sensitive data is data for which the release might be harmful.

service

In general, use the product name over service or services. Use the website for guidance.

service level agreement

Lowercase when referring to service level agreements in general.

It's OK to use title case (Service Level Agreement) when referring to a specific document.

OK to abbreviate as SLA after first use.

service level indicator

Lowercase except at the beginning of a sentence, heading, or list item.

OK to abbreviate as SLI after first use.

service level objective

Lowercase except at the beginning of a sentence, heading, or list item.

OK to abbreviate as SLO after first use.

setup

Use as a noun or adjective.

set up

Use as a verb.

she, her, hers

Don't use a gendered pronoun except for a specific individual of known gender. Use they and their for the general singular pronoun.

sherpa

If possible, use a more precise term. For example, if you mean guide, use that term.

should, should be

Generally avoid. Because should is ambiguous by definition, it can be problematic.

sign-in

Use as a noun or adjective.

sign in

Use as a verb.

simple, simply

What might be simple for you might not be simple for others. Try eliminating this word from the sentence because usually the same meaning can be conveyed without it.

since

If you mean because, then use because instead of since. Since is ambiguous; it can refer to the passage of time. Because refers to causation or the reason for something.

single most

Not singlemost.

single sign-on

Use as a noun or adjective.

smartphone, smart phone

Don't use. Instead, use mobile phone or phone. If you're talking about more than phones, then use mobile device.

soon

Avoid in timeless documentation because this word can become outdated. The word can also prematurely disclose product or feature strategy or inappropriately imply that a product or feature might change.

spin up

As in spin up an instance. Avoid using spin up unless you're referring to a hard disk; instead, use a less colloquial term like create or start.

startup

Use as a noun or adjective.

start up

Use as a verb.

status bar

Not statusbar or status-bar.

Lowercase except at the beginning of a sentence, heading, or list item.

sub-command

Not subcommand.

subtree

Not sub-tree.

subzone

Not sub-zone or sub zone.

surface

Avoid as a transitive verb; instead, use a more specific term, such as make people aware of or expose.

T

tab

When referring to the sub-pages of a console, use page instead of tab.

table name

Two words. Set specific table names in code font.

tablet

Tablet is OK. If you don't know whether it's a tablet or a phone, use device.

tap

Use instead of click when the environment is a touch device.

Use instead of touch. However, touch & hold (not touch and hold) is OK to use.

target

Avoid using as a verb when possible, especially in reference to people. For some readers, target has aggressive connotations. Instead of "targeting" audiences, we try to attract them or appeal to them or make their lives easier.

terminate

Avoid using as a synonym for stop. Instead, use words like stop, exit, cancel, or end.

they (singular)

This is our preferred gender-neutral pronoun. Whether used as singular or plural, it always takes the plural verb. For example, "A user authenticates their identity by entering their password."

third party

Use as a noun.

third-party

Use as an adjective.

this, that

Where possible, put a noun after this or that for clarity.

timeframe

Not time frame. Avoid where possible, or use an alternative such as period, schedule, deadline, or when. But if you do use it, then write it as one word.

timeout

Use as a noun.

time out

Use as a verb.

timestamp

Not time stamp.

timeout

Use as a noun.

time out

Use as a verb.

time zone

Use as a noun.

time-zone

Use as an adjective.

toolkit

Not tool-kit or tool kit.

touch

Don't use. Instead, use tap. However, touch & hold is OK to use.

touch & hold

Not touch and hold.

touchscreen

Not touch screen

traditional

If possible, use a more precise term.

turn on

In procedures, use the appropriate label and action for the UI element that the user interacts with.

tutorial

Refers to a guided learning experience designed to teach users how to effectively use a software application.

type

In general, use enter instead of type because there is typically more than one way to enter text than typing (such as pasting text or speaking).

typically

Use to describe what is usual or expected under normal circumstances.

Don't use as the first word in a sentence, as doing so can leave the meaning open to misinterpretation.

U

UI

Don't use generically to refer to a page or dashboard. Use a more specific term like page or console. If a specific term is unavailable, use web interface.

unarchive

Don't use. Instead, use extract.

uncheck

Don't use to refer to clearing a check mark from a checkbox. Instead, use clear.

uncompress

Don't use. Instead, use extract.

under

Don't use for a range of version numbers. Instead, use earlier.

Don't use to refer to a position in the UI.

Unicode

Not UNICODE.

unselect

Don't use. Instead, use clear for checkboxes, and deselect for other UI elements.

unsighted

Don't use.

US

OK to use as an abbreviation for United States. Don't use U.S. or U.S.A.

user

Use the word user only to refer to the user of the software that your reader is developing. Otherwise, address the reader as you and assume that they will complete the tasks that you're documenting.

user base

Not userbase.

using

Where using might have more than one interpretation, use by using to help clarify the logic of the sentence.

utilize, utilization

Use with caution. Don't use utilize when you mean use. It's OK to use utilize or utilization when referring to the quantity of a resource being used.

V

v (abbreviating version)

Use lowercase.

via

Don't use.

vice versa

Don't use. Instead, use a phrase like the other way around, conversely, or otherwise.

virtual machine (VM) instance

Use when first introducing virtual machines on a given page. For subsequent mentions, you can use VM instance or VM.

voila

Don't use.

vs.

Don't use vs. as an abbreviation for versus; instead, use the unabbreviated versus.

W

walkthrough

Not walk-through.

we

Don't use we (or other first-person plural pronouns such as our or us) to address the reader who is performing the tasks that you're documenting. Instead, use you.

web server

Not webserver.

while

Don't use to indicate a contrast. Instead, use a more precise term, such as although.

OK to use to refer to a period of time.

whitepaper

Not white paper.

whitespace

Not white space.

workload

The term workload might refer to software, like an app or a service; to app resources, like data and infrastructure; or to physical components that work together.

Where possible, use a more precise term to describe what you mean. If you use the term workload, define your meaning on first use as you normally would with jargon and other ambiguous terms.

would

Avoid using. Instead, use can where possible.

Y

you

Use you instead of user to address the reader of your document.

Z

zippy

Don't use.

References

The Chicago Manual of Style

Apple Style Guide

Google Documentation Style Guide

Draft.dev Style Guide

DigitalOcean’s Technical Writing Guidelines

GitLab Documentation Style Guide

CMOS Style Guidelines