-
Notifications
You must be signed in to change notification settings - Fork 593
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
- General formatting
- VuePress authoring
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.
Note: Looking for information on adding a page to the TOC? See Add a doc to the TOC.
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.
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.
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.
- 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.
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".
- 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.
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."
- For example, "The User object has a
-
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".
- When talking about the authentication methods as concepts in general, DO USE:
-
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".
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 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.
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.
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
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
---
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.
See DevDoc Image Guidelines and Process. This content includes information on alt image text.
Do not use.
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 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)
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.
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.
Folder names and filenames should be all lower case and words separated by hyphens.
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
"
- "Run
- Filenames
- "
example.js
"
- "
In request examples, replace Okta URLs with {yourOktaDomain}
:
https://{yourOktaDomain}/further/path/goes/here
Examples:
https://{yourOktaDomain}/api/v1/domains/
https://{yourAppRedirectUri}
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.
Never use underlining.
Refer to variables using the appropriate parameter format, place in curly braces.
Examples:
{clientId}
{authorizationServerId}
See Understand lifecycle and CRUD tags
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. |
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.