Skip to content

Style Guide

Jump to bottom
Susan edited this page Jun 7, 2023 · 140 revisions

This style guide should be used for all documentation on the developer.okta.com site. It can also be used as guidance for writing developer blog posts.

Contents

Note: For any topic not covered here, we use the Okta InfoDev Style Guide and the Microsoft Style Guide. If you don't find it in either this guide or in Microsoft's, refer to the Chicago Manual of Style.

Text and wording

Terminology

When you're writing, be sure to use the correct terms!

  • Get vs List: Use "List" when you are talking about getting more than one thing.

    • Incorrect: "Get all Factor Profiles."
    • Correct: "List all Factor Profiles."

  • OAuth 2.0: Use the full name and number, as opposed to "OAuth" (Unless you are referring to the endpoint /oauth).

  • Object: The objects our REST API returns. When you GET an Okta User, you are requesting an Object.

  • Okta Expression Language: Use the full name. Don't use articles with it. For example, "This document details the features and syntax of Okta Expression Language used in the Identity Engine."

  • Okta Identity Engine and Okta Classic Engine: Use the full name for the first use of the term on a page (not including front matter). Don't use articles.

    • For example, "Enhanced mail macros are supported in Okta Identity Engine."

    Identity Engine and Classic Engine: After the first use of the full name, use the truncated name for all subsequent mentions on a page. Don't use articles.

    • For example, "Enhanced mail macros are supported in Identity Engine."

  • Okta Support: To provide a CTA for those looking for support, use contact your Okta account team or ask us on our [forum](https://devforum.okta.com/). Don't use the Okta support email.

  • OpenID Connect: Use the full name unless you are referring to the endpoint /oidc. If using the full name becomes awkward in a topic, you can introduce the abbreviation on first use in the topic (for example, "OpenID Connect (OIDC)"), then use "OIDC" from then on in the topic. Use the full name in headings and titles.

  • Property: Objects contain properties.

    • For example, "The User object has a statusChanged property."

  • Redirect and embedded deployment models: When talking about the two broad categories of authentication deployment models that Okta makes available, we should use the following language as a guide.  See redirect-vs-embedded for more information on these concepts.

    • When talking about the authentication methods as concepts in general, DO USE:
      • Redirect authentication
      • Embedded authentication
    • When talking specifically about the deployment models used to achieve those authentication methods, DO USE:
      • Redirect model / Redirect deployment model
      • Embedded model / Embedded deployment model
    • In cases where you think the reader may not have any previous knowledge of authentication, you could write the following longer form to make the purpose a bit clearer:
      • Redirect authentication deployment model
      • Embedded authentication deployment model
    • DON'T USE:
      • Okta-hosted authentication model
      • Okta-hosted deployment model
      • Redirect authentication model
      • Embedded authentication model
    • Only use "Okta-hosted" when talking about the widget, for example "Okta-hosted Sign-In Widget", or "redirect to the Okta-hosted Sign-In Widget".

  • Sign in: Use "sign in" and "sign-in". See row 4 of Best practices for common issues for detailed info.

    Caveat: There are UI elements that use something other than what is defined here. We must use what is in the UI to not confuse the reader.

  • Sign-In Widget: First reference: "the Okta Sign-In Widget" Second reference: "the Sign-In Widget" or "the widget".

  • Social login: Use "social login" instead of "social authentication".

  • Style sheets: Don't use "stylesheets". It's definitely two words. This is why the abbreviation is "CSS", and not "CS".

Acronyms and abbreviations

If you need to define an acronym or abbreviation, spell it out on first use, then put the acronym or abbreviation in brackets after it. For example, "Amazon Web Services (AWS)" or "JSON Web Token (JWT)".

However, a lot of acronyms don't need to be defined like "JSON", "HTTP", and "SAML". You can use common industry acronyms (such as "SSO", "SWA"), as long as they are defined in the Okta glossary.

If you need to add a term to the glossary, create an SRB Jira for glossary additions. See Glossary guidelines and clone the SRB Jira template.

You should capitalize solo file types. For example, "GIF" and "JPEG". However, you shouldn't capitalize file extensions when you're giving the full name of the file. For example, use example.js not example.JS.

Examples:

  • Output is logged to the console as well as to a JSON log file.
  • You can upload any JPEG, BMP, or PNG file.
  • Download the package.json file.

Capitalization

  • Don't use capitalization randomly. Use lowercase unless there is a specific reason for capitalizing.
  • Use sentence case for headings. For example, use "This is a heading" and not "This Is A Heading".
  • Do capitalize:
    • Proper nouns: For example, "Microsoft" and "San Francisco".
    • Services: For example, "Identity Provider" and "Service Provider".
    • Protocols and standards: For example, "OAuth 2.0", "OpenID Connect"
    • Languages, libraries, and frameworks: For example, "Express", "Spring", "Node", and "Python".
    • Okta objects: You should capitalize the names of Okta objects, such as "User" and "Application". This helps when you're talking about modeling. For example, "The Okta User resource is used to model your application's users". Note: This doesn't mean to capitalize all instances of the word, only when you are talking about an Okta object, whether that is in a guide, a concept, or an API reference page.
  • Don't capitalize:
    • Common nouns: The common instance of something. For example, "A computer server" versus "A copy of Windows Server 2003".
    • Common technical terms: For example, use "access token" and "refresh token". (The OAuth 2.0 spec doesn't capitalize these, so why should we?)

See Product name terminology and row 2 of the Best practices for common issues,

Article use (a, an, & the)

Some product or feature names are composed of common nouns like "Okta Expression Language" or "Okta Authorization Server". To make the sentence read naturally, feel free to use articles even though they aren't normally used with proper nouns. Let spoken language be your guide here.

  • When using the terms "Okta Identity Engine" or "Okta Classic Engine", don't use articles. For example, "Enhanced mail macros are supported in Okta Identity Engine." See Terminology.
  • When using the terms "Identity Engine" or "Classic Engine", don't use articles. For example, "Enhanced mail macros are supported in Identity Engine." See Terminology.
  • When using the term "Okta Expression Language", don't use articles. For example, "This document details the features and syntax of Okta Expression Language used in Identity Engine." See Terminology.

Dates

Use the Microsoft Style Guide if you have to mention a date. Write dates using the "Month Day, Year" format. For example, "May 3, 2017".

Punctuation

  • Spaces: Use one space after periods, not two.
  • Numerals: To form the plural of a numeral, add "s" but no apostrophe. For example, "Type three 2s".
  • Apostrophes: Don't use apostrophes to form plurals of proper nouns, acronyms, and numerals. For example, the plural of "FAQ" is "FAQs", not "FAQ's". Don't pluralize single letters, symbols, or mathematical signs by adding an apostrophe and an "s".
    • Incorrect: "Salesforce replaces unrecognizable characters with @'s."
    • Correct: "Salesforce replaces unrecognizable characters with the at (@) sign."
  • Comments in code examples: If the comments are a complete sentence, use a period.

General formatting and VuePress authoring

API endpoint intros

When there is only one line for an endpoint introduction, it should be a sentence fragment without a period. When there is more information, give the first fragment a period and follow it with the additional sentences.

Examples:
Adds a new application to your Okta organization
Adds a SWA application. This application is only available to the org that creates it.

Front matter

For a standard API reference page or a guide, use front matter similar to this example:

API

---
title: Apps
category: management
---

Guide

---
title: Token inline hook
excerpt: Learn how to easily implement a token inline hook
layout: Guides
---

Headings

We use the atx style for our headers.

# This is an H1
## This is an H2
### This is an H3

The content under the front matter should not have any h1 headers - this is set by the title property. All h2 headers in the content are rendered as a link in the table of contents that renders on the right of the page.

To ensure that the heading levels are consistent, set "Request parameters", "Response parameters", "Request example", and "Response example" headings to the h5 level.

Note: Anchor tags for headings only render as lower case alphanumeric characters, along with - (hyphen) and _ (underscore), and spaces are replaced with - (hyphens). All other characters are removed. For example, the anchor tag for a heading named "Bits & Bytes" becomes #bits--bytes.

Use sentence case in all headings (only the initial word is uppercase and any "proper nouns"). See the Use sentence-style capitalization section in the Microsoft Manual of Style.

For example

End-user Notifications Actions
Okta-hosted flows
Requests sent by Okta

Don't use gerunds in titles and headings. Titles and headings should answer the question: What are you trying to do? For example, if a user decides, "I want to "Enroll in OMM", the heading of the related article should be "Enroll in OMM".

Don't use monospace code formatting in headings.

Bold

Only use for UI elements, such as dialog box titles and UI element labels. For example, "Select the People tab of your Okta OpenID Connect app and click Assign to People."

Italics

Do not use.

Lists

When providing a list of properties/parameters or any type of list of items and a description, use a colon after the item, a space, and then capitalize the first letter of the first word in the description, whether it's a fragment or a complete sentence.

For example:

  • Name: Enter a name for the Identity Provider configuration.
  • Client Id: Paste the app ID or client ID that you obtained when you configured the Identity Provider in the previous section.
  • Client Secret: Paste the secret that you obtained in the previous section.
  • Scopes: Leave the defaults. These scopes are included when Okta makes an OpenID Connect request to the Identity Provider.

List indents

If you have a text, code, or note block that belongs under an ordered or unordered list item, add three spaces to indent the block. This Markdown convention aligns the block under the list item. For example:

1. A numbered item

   The block appears indented and aligned under the numbered item.
   
   > **Note:** This note is indented and aligned under the numbered item. Add three spaces to indent code blocks as well as image tags.

Result:

  1. A numbered item

    The block appears indented and aligned under the numbered item.

    Note: This note is indented and aligned under the numbered item. Add 3 spaces to indent code blocks as well as image tags.

    extra code block example

Note: Two tabs or four spaces work as well for list indents, but use three spaces for consistency.

Definition lists

Create definition lists using the following syntax in markdown:

First term
: First definition
Second term
: Second definition

Note that while not suitable for creating multiple terms with a single definition (or vice versa), or embedding a complex series of items in a single definition, you can put multiple lines inside a single definition using HTML:

First term
: <p>First definition para</p><p>Second definition para</p>

You are advised to keep it as simple as possible.

Underline

Never use underlining.

Monospace

Use for:

  • Variable names and values
  • Methods and functions
  • Terminal commands
    • "Run DemoApplication or start it from the command line using ./mvnw spring-boot:run"
  • Filenames
    • "example.js"

JSON examples

Examples should be actual JSON requests to, and responses from, our server. Never create examples by hand. If you have any doubts about security/privacy, you are free to modify the JSON examples after you copy them, but they should always resemble real examples as closely as possible.

Domain names used in examples must either be domains owned by Okta, TLDs, or domains set aside for this precise purpose. See RFC 2606.

Variables in examples

Refer to variables using the appropriate parameter format, place in curly braces, and preface with $.

Examples:

  • ${clientId}
  • ${authorizationServerId}

Note: Request examples need variables with $, but response examples do not. The $ symbol means that a dev must input a variable. To include the symbol in a response example could be confusing.

Okta URLs

In request examples, replace Okta URLs with {yourOktaDomain} and preface them with $:

https://${yourOktaDomain}/further/path/goes/here

Examples:

  • https://${yourOktaDomain}/api/v1/domains/
  • https://${yourAppRedirectUri}

Note: Request examples need Okta URLs with $, but response examples don't. The $ symbol means that a dev must input an Okta URL. To include the symbol in a response example could be confusing.

Markdown filename and folder format

Folder names and filenames should be all lower case and words separated by hyphens.

Tables

If you have columns with unbroken text, you can ensure your table won't overlap the right nav by adding this immediately after the table:

{:.table .table-word-break}

When listing properties in tables, list them in alphabetical order. You can paste the table items into MS Word and then hit the Sort Alphabetically button, or you can install and use the Sort lines VS Code extension.

Use periods in table text only if the cells contain complete sentences or if they contain a mixture of fragments and sentences. Don't put a period at the end of a fragment.

Images

See DevDoc Image Guidelines and Process. This content includes information on alt image text.

Linking

Links to external websites should follow standard markup rules:

[link text here](https://link.to.external/doc)

Links to docs inside the developer.okta.com domain should specify the full relative paths:

[link to okta doc](/docs/doctype/subfolder/)

Links to headers within the same doc should use anchor tags (see Headings for anchor format) :

[link to doc header](#the-heading-label)

Product Doc links

Links to Okta product docs should use aliases instead of exact URLs. See Alias links for H.O.C..

Classic example: [Customization variables for email and SMS templates](https://help.okta.com/okta_help.htm?id=ext_ref_email_variables)

Identity Engine example: [Manage Profile Enrollment policies ](https://help.okta.com/okta_help.htm?type=oie&id=ext-create-profile-enrollment)

Global components

Some documents on the site contain references to reusable text snippets. These references are replaced with the matching content from files located in the packages/@okta/vuepress-theme-prose/global-components directory. For example, the <ApiLifecycle access="ea" /> tag in the Customize email templates source file is replaced with the content from the ApiLifecycle.vue file, customized with the access prop passed into the component.

Note: Reach out to the developer documentation team if you want to create a new text snippet.

API CRUD and lifecycle tags

See Understand lifecycle and CRUD tags

Endpoint URLs

When you mention an endpoint in any Developer Doc content (including both bugs, features, and enhancements in the API Release Notes), always include the full path that follows /api/v1/ for all endpoints except OAuth endpoints. For OAuth endpoints, always include the full path that follows /v1/.

Also, when referencing an endpoint in any content, always be sure to provide a link to the endpoint API Reference page. Use the word "endpoint" to insert the link.

Good: If a user was converted to use an external Federated IdP instead of Okta, any subsequent attempt to convert the user with a call to the /users/${userId}/lifecycle/reset_password endpoint returned an HTTP 501 error instead of an HTTP 400 error.

Bad: When attempting to reset a user's password using the lifecycle/reset_password endpoint, admins received an HTTP 500 error code rather than a valid error message if the user's email address was invalid.

Good OAuth Example: When an OAuth service client called the /authorize endpoint, the returned error description was inaccurate.

Good Release Notes Example: During user import, some POST requests to the /users endpoint incorrectly triggered Inline Hooks, resulting in higher latency. (OKTA-335769)

When referencing operations performed on an endpoint, mention the operation and link to that specific operation for the endpoint in the API Reference content.

Good Release Notes Example: When the Create a new Binding or the Add more Members to a Binding operation was performed on the /resource-sets endpoint, and included all users or all groups in the request, the request didn't fail as expected. (OKTA-459994)

When referencing .well-known endpoints, include the full path after the Okta base URL:

For example:

/.well-known/openid-configuration

/.well-known/oauth-authorization-server

/oauth2/{authorizationServerId}/.well-known/openid-configuration

/oauth2/{authorizationServerId}/.well-known/oauth-authorization-server

cURL snippets

cURL snippets should resemble the following:

curl -L -X POST "https://{yourOktaDomain}/idp/idx"
  -H "Content-Type: application/json"
  -d "{
    "stateHandle" : "{{stateHandle}}",
    "identifier" : "{{username}}"
}"

You can generate this type of output in Postman by navigating to Code > Generate Code Snippet > cURL.

Left side navigation

The left side navigation (or tree nav) provides structured links to all the different articles available on the site. If you want to modify the tree nav, edit the following file:

packages/@okta/vuepress-theme-prose/const/navbar.const.js

Inside this file there is a separate exported object that contains the tree nav data for each major docs section (Guides, Concepts, References, etc.).

For example:

export const concepts = [
  …
];

Create a link to an article

Add a new object to represent each linked article at an appropriate place in the hierarchy. This object should contain the title of the article, and a reference to the document to link to, for example:

{
  title: "Okta email",
  guideName: "authenticators-okta-email",
},

The title is always contained inside a title property. Note that at the moment the title is always set equal to the title property contained in the linked article's index.md frontmatter — you currently can't override it by setting the tree nav title to something different. We are hoping to fix this in the future; for now, the best practice is to set it to a sensible shortened version of the article title, as appropriate.

The reference to the document to link to can be set in one of two ways:

  • Inside a guideName property, as shown above. This is the recommended way to set it for articles inside the guides tree nav data because you only have to specify the article's directory name, and the system sets up some useful features automatically when this is done.

    However, bear in mind that:

    • To use guideName successfully, you also have to include the article's name inside the guides property of the packages/@okta/vuepress-site/docs/guides/index.md frontmatter.
    • As implied above, you can only use guideName for guides.

  • Inside a path property, as shown in the example below. When using path you have to specify the entire path to the article folder relative to the vuepress-site directory, for example /code/react/ or /docs/reference/api/authn/.

    {
   title: "Policies",
   path: "/docs/concepts/policies/",
},

Note: You can only link to standard articles contained inside the dev.okta source code from the tree nav — you can't link to external URLs or non-standard/one-off pages.

Create a sub-landing page

If you want to group a set of articles underneath a sub-landing page, you can do so by adding them into an array inside a subLinks property, inside the sub-landing page object.

For example:

{
  title: "Understanding IAM",
  path: "/docs/concepts/iam-overview/",
  subLinks: [
    {
      title: "Identity management factors",
      path: "/docs/concepts/iam-overview-identity-management-factors/"
    },
    {
      title: "Authentication factors",
      path: "/docs/concepts/iam-overview-authentication-factors/"
    },
      …
  ]
},

Note: This structure works recursively — any article placed underneath a sub-landing page can itself be turned into a sub-landing page. However, best practice dictates that you should ideally use no more than three levels of nesting below each major docs section, to mitigate complexity.

When rendered, a sub-landing page link is displayed with a small chevron next to it. Clicking the chevron opens the sub-directory to show the articles grouped underneath it. Clicking the link displays the sub-landing page link as well as opening the sub-directory.

Specify what page is displayed when a sub-landing page link is followed

When you click on a major docs section in the horizontal navigation (e.g. Guides), the landing page you see is defined in the index.md file inside the root of that section of the source code, for example packages/@okta/vuepress-site/docs/guides/index.md for the Guides landing page.

For sub-landing pages, it works a bit differently. Unless otherwise specified, following a sub-landing page link will display an auto-generated list of links to the pages underneath it, plus a description of each one. For example, the Redirect authentication sub-landing page source looks like this:

{
  title: "Redirect authentication",
  subLinks: [
    {
      title: "Sign users in to your single-page application",
      guideName: "sign-into-spa-redirect",
    },
    …
  ],
},

The rendered page looks like this:

If you want to show a custom landing page instead of the default auto-generated page, you need to reference it inside a guideName or path property, just like you do for regular links. For example, the Sign users in sub-landing page source looks like this:

{
  title: "Sign users in",
  guideName: "sign-in-overview/main",
  subLinks: [
    …
  ],
},

When "Sign users in" is clicked in the tree nav, the page defined in the source at guides/sign-in-overview/main is displayed.

Specify a custom abstract for an article

When an article link and abstract are shown on an auto-generated sub-landing page, the default abstract shown is the first regular paragraph contained in that article's index.md source. If you want to instead show a custom description, you include the custom text inside a "slot description", at the top of the index.md source.

For example:

::: slot description
Add embedded authentication to your SPA app with Okta Auth JS.
:::

Category links

If you need to include a list of links for a category group which was defined in the frontmatter, you can use the CategoryLinks component.

As long as you have the category defined in your markdowns frontmatter, such as:

---
category: myCategory
---

You can then use the <CategoryLinks> tag:

<CategoryLinks category="myCategory" />

A few options are provided to allow for customization:

Property Description
category The category you want to display for the links. This is based on your markdown frontmatter
linkPrefix [ADVANCED] This property allows you to include links based on the path, instead of a category
sort Allows you to sort based on the defined property
showExcerpt This property defaults to true and will display the frontmatter excerpt

Clone this wiki locally