Style Guide

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.

Text and wording

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.

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.

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.

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 two of the Best practices for common issues.

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.

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".
#: Use "#" 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".

General formatting

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."

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.

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.

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

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.

Images

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

Italics

Do not use.

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.

Links

Links to external websites should follow standard markdown 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)

Links to 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)

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:

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.

Markdown filename and folder format

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

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"

Okta URLs

In request examples, replace Okta URLs with {yourOktaDomain}:

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

Examples:

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

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.

Underline

Never use underlining.

Variables in examples

Refer to variables using the appropriate parameter format, place in curly braces.

Examples:

{clientId}
{authorizationServerId}

VuePress authoring

API CRUD and lifecycle tags

See Understand lifecycle and CRUD tags

Category links

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

As long as you have the category defined in your markdown front matter, 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 front matter.
linkPrefix	[ADVANCED] This property allows you to include links based on the path, instead of a category.
sort	This property allows you to sort based on the defined property
showExcerpt	This property defaults to `true` and displays the front matter excerpt.

Reusable text snippets

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.

URL redirects

See Edit URL redirects

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Style Guide

Contents

Text and wording

Acronyms and abbreviations

API endpoint intros

Article use (a, an, & the)

Capitalization

Dates

Punctuation

Terminology

General formatting

Bold

cURL snippets

Definition lists

Endpoint URLs

Front matter

Headings

Images

Italics

JSON examples

Links

Lists

List indents

Markdown filename and folder format

Monospace

Okta URLs

Tables

Underline

Variables in examples

VuePress authoring

API CRUD and lifecycle tags

Category links

Reusable text snippets

URL redirects

Clone this wiki locally