Skip to content

Style Guide

Jump to bottom
Chris Mills edited this page Jul 21, 2022 · 137 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."

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

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

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

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

  • Property: Objects contain properties.

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

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

  • 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/). Do not use the Okta support email.

  • Sign in: Use "sign in" and "sign-in".

    • Don't use "login", "log in", "log-in", "log off", "log-off", "signon", "sign on", or "sign-on".

      Exception: If you spell out SSO, "Single Sign-On" is allowed.

    • Use a hyphen when it's an adjective. For example, "sign-in page" or "sign-out URI".

    • No hyphen when it's a verb. For example, "Sign in to the app".

    • Avoid the use of sign-in as a noun, for example:
      Incorrect: ".....can initiate the sign-in."
      Better: "...can initiate the sign-in request."

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

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

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.

Solo file types should be capitalized. 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

  • Do not 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?)

Usage of articles (a, an, & the)

Some product or feature names are composed of common nouns like "Custom Authorization Server" 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 the 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, use front matter similar to this example:

---
title: Your title
excerpt: A short description
---

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 will be set by the title property. All h2 headers in the content will be 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 will only render as lower case alphanumeric characters, along with - (hyphen) and _ (underscore), and spaces are replaced with - (hyphens). All other characters will be 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

Avoid using 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 is 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 have a text, code, or note block that belongs under an ordered or unordered list item, add 3 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 3 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: 2 tabs or 4 spaces work as well for list indents, but use 3 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 once you have copied 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 do not. 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 for H.O.C. documentation.

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)

Note: As of September 2021, the base URL has now changed for both classic and Identity Engine alias URLs. The alias documentation link will be updated soon. The links above are accurate, namely use https://help.okta.com/okta_help.htm?id= for a classic base URL (no #) and https://help.okta.com/okta_help.htm?type=oie&id= for an Identity Engine URL. Always check to make sure your alias URL renders.

URL redirects

Redirect links are maintained for legacy bookmark support. They are listed in the conductor.yml file, which is located in the packages/@okta/vuepress-site directory.

Note: The redirects specified in the conductor.yml file are only functional on the live documentation site and can't be tested when using yarn dev to build the site locally. For more information on locally building the site, see Getting set up and Contributing to the Site.

Page Redirects
You must create two redirect links for each legacy link you want to update, which ensures that multiple URL variations of the legacy link resolve to the new path.

To create a redirect from old/path/1 to new/path/2, you need to add the following redirects:

  • - from: /old/path/1/index.html
  • to: /new/path/2/
  • - from: /old/path/1 <-- NOTE: Make sure NOT to include a forward slash on this from redirect.
  • to: /new/path/2/

The two redirect links ensure that anyone who has a bookmark, or types in, the URLs /old/path/1/, /old/path/1, or old/path/1/index.html resolve correctly to the new URL (/new/path/2/).

Ensure that all legacy links point to the latest version of the page in question. If a page has been renamed more than once, make sure there are redirects for all versions of the page. For example:

  • old/path/1 -> new/path/3
  • old/path/2 -> new/path/3

Guide Redirects
After you create a guide, if that guide is then renamed, in addition to the redirects for the guide's new name, you must add redirects for the guide path that includes /-/:

  • - from: /docs/guides/guide-old-name/-/section1/
  • to: /docs/guides/guide-new-name/section1/
  • - from: /docs/guides/guide-old-name/-/section2/
  • to: /docs/guides/guide-new-name/section2/

and so on....

The /-/ portion of the URL is always there as a placeholder for language selection (stack selectors), even if the guide doesn't have stack selectors.

Note: You can't use the regular convention for Help Okta Doc aliases in the conductor.yml file. The build fails when a URL contains the ? and = characters. Instead, use the following convention until we can address this issue in our redirect process:

  • OIE: https://help.okta.com/oie/en-us/okta_help_CSH.htm#<alias-identifier>
  • Classic: https://help.okta.com/en-us/okta_help_CSH.htm#<alias-identifier>

Troubleshooting

  • Ensure there is one non-blank line at the end of the conductor.yml file, otherwise an error is thrown during tests.
  • Ensure that formatting, tabbing, and spacing are exact as existing redirects.

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.

API CRUD tags

CRUD operation graphics are rendered using the following code:

<ApiOperation method="CRUDOperationHere" url="/api/v1/path/goes/here" />

Available operations are:

  • post
  • get
  • put
  • delete

For example, this Markdown:

<ApiOperation method="delete" url="/api/v1/apps" />

would render as:

Lifecycle tags

We have special markdown tags and a custom plugin which enables you to mark content as Early Access and Deprecated in the API docs.

Note: Apply the tag to the top of the file after the title if the whole API is affected by the status. Otherwise, apply it to the most appropriate section, or next to the property name in a table.

  • Early Access content: <ApiLifecycle access="ea" />
  • Deprecated content: <ApiLifecycle access="deprecated" />

For example, if you add:

<ApiLifecycle access="beta" />

it would render as:

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

If you want to add something to the navigation bar, edit the following file:

packages/@okta/vuepress-theme-prose/const/navbar.const.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