Grammar and mechanics

Grammar is the structure of written content, including parts of speech and how words are organized to create phrases and sentences.

Mechanics are the rules of written content, including capitalization, punctuation, and spelling.

Following grammar and mechanics rules help make content clear and consistent.

Note: These guidelines focus on American English used in Okta Workforce products. Internationalization is referred to but guides used by our translators include required grammar and mechanics for each language.

Grammar

Sentence structure

Use simple words

Use the simplest word that is appropriate to make things easy to understand for all users. While Okta builds technical products, our language should aim for a grade eight level of understanding. Complex topics may include more complex vocabulary when absolutely necessary.

Short, simple words makes reading faster and easier.

Learn more about our vocabulary in the Product glossary.

Use short sentences

Keep sentences short and simple by revising or removing wordy or redundant phrases. A maximum of 10-15 words per sentence achieves peak readability. Every additional word reduces comprehension.

Use active voice

Focuses on the user and the action they need to take.

In some cases, like error messages, passive voice is more appropriate to explain the error rather than seeming to blame the user for making the error. Learn more about error messages.

Use the right tense

Present tense

Use the present tense to describe product behavior. Avoid using the future tense to describe the way a product always acts.

Past tense

When you need to write in the past tense, use simple verb forms. Avoid verb tenses with the words have, has, had, been, should, would, and will.

Future tense

When you are describing results after an action has been carried out, write in future tense.

Use statements instead of questions

If every input asks a question, it increases users’ mental load and can create a sense of uncertainty, weakness, or passivity.

Don’t use qualifiers (steps)

Qualifiers that imply steps create an issue if the feature flow has steps added or removed. If users need to know where they are in a flow, consider using a progress bar component. Or, use an ordered list in support copy to clearly explain steps.

Page titles shouldn’t include: start, now, next, last, or finally.

Parts of speech

Adverbs

Try to remove adverbs to keep sentences concise and clear. For example, carefully, extremely, sometimes, and often are modifiers that weaken verbs or duplicate their meaning.

Pronouns

You and Your

Use you and your to directly address the user. This focuses text on the user.

We and Our

Use these pronouns when Okta employees require information or are involved. Don’t use we and our for automatic processes when Okta employees aren’t involved.

My or Me

Avoid using my or me. It can cause confusing tense switching in experiences like: Change your preferences in My Account.

Mechanics

Abbreviations, acronyms, and initialisms

1. Use abbreviations, acronyms, or initialisms when it's absolutely necessary for space.
   In headlines and subheadings
   For space, use the abbreviated name or acronym and then spell out the term in parentheses. For example, SCIM (System for Cross-domain Identity Management). Double-check the glossary for terms that don't require parenthetical.
   In text
   Spell out the first use and include the abbreviated name or acronym in parentheses after the full term. In general, don’t include the acronym in parentheses if the term is used only once.
2. Use the acronyms or initialisms when they've become so common that they’ve replaced their original terms. These include:

• ACR instead of Authentication Context Class References
• AD instead of Active Directory
• AES instead of Advanced Encryption Standard
• AJAX instead of Asynchronous Javascript and XML
• API instead of Application Programming Interface
• AWS instead of Amazon Web Services
• BCP 47 instead of Best Current Practices 47
• CAPTCHA instead of Completely Automated Public Turing Test to Tell Computers and Humans Apart
• CDN instead of Content Delivery Network

Learn more about Okta acronyms and initialisms

• Product glossary
• That Acronym List (Confluence)
• Okta and Industry Terminology (Confluence)
• In Slack, type: /whatis [acronym]

Ampersand (&)

Use an ampersand instead of and only when needed for space in headlines, tables, links, or buttons. Product doesn't use the + that brand uses instead of an ampersand.

Bold

1. Use bold to identify labels or instructions in UI copy instead of quotation marks to increase scanability. This style is consistent with help.okta and dev.okta. Engineering note: It’s best to apply bold style in CSS as being specific to English.
2. Don’t bold individual words that aren't labels or instructions to create emphasis.

Capitalization

Sentence case capitalization

Sentence case capitalizes only the first word in a phrase, sentence, or title and any proper nouns (people, places, and products). This includes:

• Titles
• Headings and subheadings
• Button labels

Sentence case improves readability and helps proper nouns clearly stand out. It also aligns North American English with globalization since many languages use less capitalization than English.

Full capitalization

Some components use full capitalization sparingly for content hierarchy and distinct typography. Use is limited because full capitalization can slow reading and be perceived as less legible.

If designing a component variation that may require using full capitalization:

• The use should be limited to small areas and short text.
• Each phrase should be one to three words.

Elements that use full capitalization

• Navigation labels
• Card category headers
• Tab labels
• Table headings
• Email eyebrow labels and navigation
• Workflow logic
• Status indicator labels

Product capitalization

Okta products are capitalized as proper nouns. If the same term can be used as a common concept or idea it isn't capitalized. For example, Okta offers Multifactor Authentication vs. Admins should always implement multifactor authentication.

UI label capitalization

Match the capitalization of the UI label.

Colons

Use to indicate that closely-related information follows. If using a colon in a sentence, don’t capitalize the text after the colon if it's not a complete sentence. For example, Tone: concise, conversational, friendly, respectful. vs Hackathon: A week to work on new, cross-funtional projects.

When a colon introduces a list, the text that precedes the colon must be able to stand alone as a complete sentence.

Don’t use colons with headings, subheadings, or labels.

Commas

Use commas to separate certain kinds of clauses and items in a series. In a series of three or more items, use a comma before the final item to avoid potentially changing the meaning of the sentence. This comma is called a serial comma or an Oxford comma.

Contractions

Use common contractions to be more conversational and readable and less overly formal and robotic.

Common contractions

• doesn’t instead of does not
• can’t instead of cannot
• don’t instead of do not
• won’t instead of will not
• you’re instead of you are
• you’ll instead of you will
• we’re instead of we are
• we’ll instead of we will
• let’s instead of let us
• it’s instead of it is
• that's instead of that is

Note: Use let’s with caution. It’s a contraction of let us and implies action by Okta. For example, Let’s check your email could be interpreted as Okta having access to a customer’s email rather than instructing them to check their email.

Currency

Identify the currency source. Currency isn't translated. For example, 100 USD instead of $100.

Dashes

Em-dash (—)

Use sparingly to create an emphatic pause and set off text in headlines and support copy. Include spaces before and after the em-dash.

Okta — not our competitor — was the best match for Imaginary Co.

Tip: The Mac shortcut is Option + Shift + Hyphen

En-dash (–)

1. Use to separate two related values. For example, 10–12 apples.
2. Use in data tables to indicate a cell is empty.

Tip: The Mac shortcut is Option + Hyphen

Hyphen (-)

Use for compound adjectives. Exception: Compound modifiers that include an adverb ending in the suffix -ly do not get hyphenated.

Dates

When a date includes the month, day, and year, use commas. Otherwise, don’t use commas.

• November 8, 2022
• On November 8, 2022, we released Okta FastPass.
• November 8

Don’t use ordinals. For example, October 4th and January 3rd.

In sentences

Write out all months fully.

In tabular text (lists, charts, tables, email subject lines, web pages)

Abbreviate dates and months as follows:

• Months: Jan., Feb., Mar., Apr., May, June, July, Aug., Sept., Oct., Nov., Dec.

In components with cells and inputs (text field - date variant, select, dialog, table, tags, date picker, status, and list)

Use numerical dates to be more consistent and fit the space more easily.

• For example, 3/27/23
• Translation will order the date appropriately. For example, 27/3/23.

Decades and centuries

For decades, don’t use an apostrophe before the s when using four digits, but use an apostrophe when using two digits: the 1980s, the ‘80s.

For centuries, use the ordinal. For example, 20th century (noun), or 21st-century (adjective).

Days of the week

Abbreviate days of the week in tabular text or if needed for space: Sun., Mon., Tues., Wed., Thurs.,  Fri., Sat.

Directional language

Remove directional prepositions to avoid responsive design and accessibility issues. These include: below, above, to the left, to the right, and under.

• Instead see if you can use an action verb, or an InfoDev practice, like replacing below with following.
• Or, see if you can delete the direction entirely.

Ellipsis (...)

Avoid using in the UI as this expresses a trailing or incomplete thought. One exception is the circular progress component that conveys loading is incomplete.

Emojis

While emojis can be delightful, they have voice and tone, visual design, accessibility, and globalization considerations. Before using emojis, ask:

• Is the experience informal?
• Is the design improved by non-ownable, non-brand decorative visual design (with potential variations by OS)?
• Is the emoji tagged properly and it is supported by clear text?

Check meanings in the Emojipedia.

These guidelines don’t need to be followed for internal use (Figma navigation and Confluence pages), but they would assure accessibility and clarity for all teams as well.

Exclamation point (!)

Use exclamation marks sparingly to support a positive tone. For example, if creating an onboarding experience or celebratory confirmation, use one exclamation point for the final headline.

• Don’t use exclamation points to substitute for good copy. If the sentence is exciting, the content will speak for itself. And, if this sentence isn’t exciting, this can convey a sense of anxiety, scolding, or panic.
• Don’t use exclamation points negatively. For example, as part of an error message.
• Don’t use exclamation points repeatedly in a flow.

Footnotes

Try to find a way to work content you want to footnote into the experience. Only use footnotes if they are absolutely necessary, for example, if the content would have to be repeated or combined in multiple ways on the same page or screen.

If footnotes must be used:

1. Use anchor-linked superscript numbers for more than one source. If there’s only one source, substitute the footnote number with a superscript asterisk (*).
2. Place footnote symbol or number with the relevant word or phrase.
3. Keep the explanatory content as close to the footnoted content as possible.

Italics

Avoid italicizing text. Use of italics varies by language and it reduces readability, particularly for people with dyslexia.

Line length

The maximum number of characters allowed on a line is 55. Once the maximum is reached, text will automatically wrap to another line. Use the Typography.lineLength.max token.

Numbers

Spell out one to nine and use numerals for 10 or more. If you have to give instructions using numbers under 10, follow this format: Enter two 3s.

• Numbers should always be used for hours, measurements, amounts, and percentages.
• Spell out million, billion, and trillion. If needed for space, abbreviate only millions (M) and billions (B).
• Any number that starts a sentence should be spelled out.

Commas in numbers

Use commas in numbers that have four or more digits. For example, $1,024 and 2,093 MB.

Exceptions

• For years, pixels, or baud, use commas only when the number has five or more digits. For example, 10,000 B.C. and 10,240 x 4320 pixels.
• Don't use commas in page numbers, addresses, or after the decimal point in decimal fractions. For example, page 1091, 15601 Market Street.

Percentages

Use the % sign in all cases, except at the beginning of a sentence. If a percent appears at the beginning of a sentence, spell out the number and use the word percent.

• Five percent of people hate the Oxford comma.
• But 95% of people approve of the Oxford comma.

Over-promising and absolutes

Remove words that over-promise or present an absolute. These include: just, easy, easily, and never.

These conditions may not be true for all users and if we can’t guarantee them to be true, they can damage trust in our experiences.

Parentheses

Avoid using parentheses because they don’t convey the same meaning when internationalized and translated. Try to work this information into your content. Or, ask yourself if these asides are essential information that needs to be included.

Pluralization

Don’t format terms to indicate either singular or plural. For example, group(s), tenant(s), rule(s). This is untranslatable and it may be understood as a type of split plural in some languages.

If multiple selections are possible, use the plural. Or, if information can be presented dynamically, write multiple versions:

• 0 groups
• 1 group
• {{2}} groups

Possessives

In general, add 's to the end of the word. For a plural noun that ends in s, add an apostrophe but no additional s.

Exceptions

• Brand now allows Okta to be possessive. For example, Okta's.
• But, don’t make feature names, products, or trademarks possessive. Use the name as a modifier or rewrite to use a word like of to indicate the relationship.

Punctuation

Use end punctuation, usually a period (.), for full sentences.

Quotation marks

Avoid extra characters and improve content readability by avoiding using quotation marks. If referring to a label or instruction, use bold instead.

Slash (/)

Avoid using to replace words or spaces. For example, Country or region not Country/region.

Terms of politeness

Avoid overusing terms of politeness such as please and thank you in a UI:

• They can convey the wrong tone for technical material.
• They can be inappropriate or offensive in some cultural contexts.
• They become insincere and meaningless if overused.
• Reserve them for when Okta has an issue that inconveniences a user. For example, a backend issue that prevents a user from completing a task. See Errors

That vs. which

Use that at the beginning of a clause that’s necessary for the sentence to make sense. Don’t use a comma before that.

Use which at the beginning of a clause that adds supporting or parenthetical information. If you can delete the clause and the sentence still makes sense, use which and put a comma before it. For example,

• Any device that is fitted with a camera can be used to authenticate users.
• Single sign-on relies on federated identity, which shares attributes across trusted, autonomous systems.

Time

Use numbers for specific times, with a space between the time and the a.m. or p.m. At the hour, do not include :00.

• 2 p.m.
• 1:45 p.m.
• 8-9 a.m.
• 9:30 p.m.-1 a.m.
• 2-2:20 p.m.

Use noon and midnight rather than 12 a.m. or 12 p.m. unless time is part of a range. For example, 11 a.m.-12 p.m.

Time zones

Use the abbreviations EST, CDT, etc., with the first reference to a time zone as part of a specific time.

• Eastern Standard Time
• noon EST
• 9 a.m. PST

Timestamps

Consider your data and put the unique information first. For example, if all the actions could occur on the same date, begin with time. If actions occur on different dates, lead with the date or use only the date.

• 2:15 a.m. - 4:45 p.m. on 4/1/23

Timestamp pattern

Truncation

Truncation, or shortening, is used for static text or links that exceed the size of their container. We avoid truncation as much as possible because it reduces usability and requires additional accessibility measures.

Truncated items are represented by an ellipsis (...). If possible, include a tooltip on hover to show the entire string, name, or phrase that the ellipsis is representing, except if the truncation is at the end of a paragraph.

Tip: Work with your Eng partners to avoid mid-line truncation because lots of information can be lost when translated. For example, don’t truncate button labels at the mid-line because crucial characters are lost in Japanese. See Internationalization

UI element names

To refer to a UI control or element, mention it using its label text only. Don't include the type of element or control.

URLs

When providing an example URL or URI to explain what input is expected, use <https://example.com> rather than <https://www.okta.com> to make it clear that this is an example URL or URI, rather than a specific Okta URL requirement.

Note: Brand style doesn't include http:// or https:// but product style includes to ensure users can access the correct URL if they need to enter it manually.

Resources

• Merriam Webster - Consult for spelling of words not included in the Product glossary.
• The Chicago Manual of Style (17th edition) - Consult when guidance is not provided by Odyssey.

Have questions or need support?

Oktanauts can use the following resources when building with Odyssey:

• Check the Odyssey 1.0 FAQs.
• Join #odyssey in Slack and tag @content to ask questions.
• Attend Odyssey Office Hours on Mondays and Wednesdays from 1-1:30 p.m. PT / 4-4:30 p.m. ET.
• Submit bug reports and feature requests to the Odyssey Jira board.