Writing for product

Using the Okta voice and tone to create a clear, understandable, consistent product that is recognizably Workforce. Learn more about our voice and tone.

Using our vocabulary supported by simple words, and specific details make Workforce experiences as easy to understand as possible. Learn more from the Okta product glossary.

Provide only the details needed to understand a feature, action, or state in short sentences. This helps users focus on their tasks and respect their time.

While Odyssey components are designed and built to meet accessibility requirements, the content within components also has to be accessible. Learn more about accessibility.

• Use simple words and short sentences.
• Provide clear headers and labels that help users orient themselves and understand tables, lists, and checkbox or radio groups.
• Create any ARIA or ALT content required by a component. See the component guidelines.
• Don't use color alone to identify a state or status.

While Okta has globalization specialists and teams of translators, content needs to be easy to translate. Learn more about internationalization.

• Use Okta vocabulary consistently.
• Design for text expansion.
• Anticipate needing 30% more space. Test with German to see if content length breaks your design.
• Work to make content concise to avoid truncation and wrapping. Both make it more difficult for users to easily scan content, understand what to do, and achieve their tasks.
• Avoid italics.
• These can not only be treated differently, or not exist, in other languages.
• Avoid split user inputs. For example, Add [user] to group [admin].
• Avoid pluralization. For example, tenant(s).
• Correct copy versions have to be presented dynamically. For example 1 tenant, 2 tenants.

Users should read the title and understand the purpose of the component or screen.

• Tell users what they need to do or know.
• Focus on the benefit or impact to users.
• Use an appropriate tone: generally positive and empowering.
• Be succinct and scannable.
• Use sentence case.
• Don’t use punctuation.
• Don’t include Okta, or we, unless absolutely necessary.
• Avoid using a question unless absolutely necessary.
• Questions can create a sense of uncertainty instead of guidance.

• Explain the button’s intended result (the action that occurs when users interact with the button).
• If very common, use just the verb. For example, Cancel, Delete.
• Otherwise, follow a verb + noun pattern. For example, Add group.
• If you have a verb in the title, reuse it in the button to reinforce the action.
• Don’t include articles and prepositions in button labels.
• Don’t use conversational phrases. For example, Not now, thanks
• Use sentence case.
• Don’t include punctuation.
• See the button guidelines.

While we design to prevent errors, they still occur. When users encounter an error, it’s crucial we help them resolve it quickly and easily to get back to their task. Learn more about writing error messages.

• Explain what went wrong. But, don’t make the user feel like they did something wrong.
• Use passive voice as necessary to avoid blame. For example, don't begin errors with you.
• If there’s a solution, give it in the second phrase or sentence.
• If there’s not a solution, provide troubleshooting instructions.
• Use an appropriate tone: generally explanatory and helpful.
• Be honest but not apologetic unless the error was caused by Okta.
• Don’t be tersely technical. For example, Invalid entry.