This style guide will cover the terminology and content specific to Auth0, along with some comments on common writing issues.
For general software-industry styles and terminology, see the Microsoft Manual of Style.
Speak to the reader directly so that your document reads as if you were engaged in conversation. Address the reader as "you." Do not use indirect language such as "one" or other passive references. Avoid "we".
The active voice is most clear. The use of passive tense can confuse or mislead the reader. Avoid constructions such as "the function was called" or "the password was entered." Instead, state exactly who or what issued the call or entered the password. Never leave the reader with uncertainty about cause and effect.
When directing the reader to perform a task, you can often omit the subject of the sentence: "Click Save."
Gerunds make statements more passive. To discuss actions the reader must take, use the imperative form, not the gerund. For example, in a section about setting up SSH keys in which you are walking the user through the process, title the subhead "Set up your SSH keys" rather than "Setting up your SSH keys."
The use of "should" and other ambivalent statements should be avoided. If something is required, tell the user it "must" be performed.
Use "can" for most descriptions of available actions. Use "may" rarely and only for cases when the action is optional. Avoid "might".
When a sentence cannot be constructed without a pronoun, the best solution for avoiding gender-specific pronouns or repetition of the subject is to use singular they: "The user enters their password."
Keep paragraphs short for internet reading.
Subheads are not intended to make independent statements. Therefore, reiterate in the paragraph text anything stated in the subhead. Do not use a subhead to introduce a separate idea and do not force the user to read the subhead to understand the text that follows.
Abbreviations should be avoided, including the use of e.g. Instead, use "for example." You want the content to flow smoothly, uninterrupted by questions the reader must ask himself regarding your intentions.
Avoid contractions in most cases; they sound too casual. Complete words are more authoritative.
Compound words may be used in three forms: one word, two words, or hyphenated.
For example, when referring to something that happens at "run time", the proper format is two words. When referring to the "runtime engine", the proper format is a single word. And when using it as an adjective, such as "run-time execution", the proper format is the hyphenated form.
Other commonly encountered compound words include "server side" and "client side". The same rules apply. When you write code for the "client side", you use two words. When you write "client-side code", the adjective form uses a hyphen. "Client side" and "server side" are never single words (clientside).
Colons are useful when you are directly referring to an example, such as "Here is the relevant code:"
Hyphens are used between adjectives and the verb they modify if and only if the adjective does not end in "ly." Therefore, "commonly used adjectives" is not hyphenated, while "oft-quoted phrase" is.
In American English, punctuation properly belongs inside quotation marks. Therefore, if you incorporate a quote into a sentence, either within or at the end, such as our editor said "You must end quotations with periods inside the quotation marks," you would construct the quotation as shown here, with the comma inside the quotation marks.
The exception is when quoting code. If the code does not include the punctuation mark, do not place the punctuation mark inside the quotes.
Only the first level title should be in "Title Case". All subheads should be in sentence case.
Use Bold when referring to menu items or fields in a webpage or UI.
Use code_formatting to refer to parameters and values.
The text of a link to additional information should be the title of the destination page, so the reader has some idea of the content being linked to.
Check the UI Components section on the contributing guide for a quick guide on how and when to use these elements.
Only use blockquotes for actual quotes, don't use them for the component styles.
Depending on the situation, the reader can "gain access", "grant access", or "allow access".
Refer to the developer's customer as the "user". Be sure to keep the idea of the user separate from the "you" of the developer being addressed.
The Auth0 management console is referred to as the "dashboard".
For more information refer to WORDS.