Writing for product

To help you create useful, accessible, translatable, on-brand content, use these guidelines. 

Prepare to write

 

Answer these questions about your content

  1. Who is your audience?
  2. What are the audience’s goals (what do they want to accomplish)?
  3. What are the business goals for the content?
  4. What devices will the customer use to experience the content?
  5. How will the customer find the content?
  6. Will the customer need content outside of the product to complete their task? For example, documentation.
  7. Do you have any user feedback or research that’s relevant to the content? For example, users don’t understand a term or concept.
  8. How will you know if the content is successful? For example, 80% of organizations adopt a new feature via the Admin Dashboard.

 

Outline the content flow to guide your design

  1. Focus on the primary goal of the flow.
  2. Order the experience sequentially to provide information as it's needed.
  3. Use content hierarchy to make the importance of information clear. Each screen should have only one to three concepts or tasks (primary, secondary, tertiary).
  4. Decide how the content needs to be presented for users to understand it and take the correct action. For example, use a table to display sortable, filterable data.

Write your draft

Follow these best practice guidelines.

Use Okta voice and tone

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

Use Okta vocabulary

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.

Be concise

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.

writing-for-prod-4
Be accessible

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.
Be translatable

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.

 

Focus on important text elements

User scan the most prominent content to understand what they need to do.

 

Titles

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.
writing-for-prod-6
Button labels
  • 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.
writing-for-prod-7

When users read the support copy, they should find concise, crucial/important secondary details that support the title.

  • Include only the details users need to complete the task or make a decision.
  • Be clear and concise.
  • Use an appropriate tone: generally informative.
  • Put the most important information at the start of the sentence or paragraph.
  • Keep sentences to 10-15 words maximum.
    • The longer the sentence, the more reading comprehension declines. On average, 14 word sentences score 90% on comprehension.
  • Keep paragraphs to three sentences maximum.
    • If not help content, or required by legal, a screen or page shouldn’t have more than one to two paragraphs.
  • If copy includes a list of items, explore using an unordered list.
  • If copy includes steps, create an ordered list.
  • If copy is complete sentences, use end punctuation.
    • This is usually periods.
    • If celebratory and positive, 1 exclamation point could be included per screen. But, you may want to use it on the headline.
writing-for-prod-8
Error messages

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.
writing-for-prod-9

Learn more

See each component for specific content guidelines.

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
  • Request a new component using the Odyssey component proposal.