Skip to main content

Style Guide

Here are a few guidelines to ensure that the documentation is easy to read and uses similar phrasing. Remember to use our docs templates when possible; they are already set up to follow may of the style guidelines below.

If you find any documentation that doesn't match these guidelines, feel free to either open an Issue or a PR so they can be fixed.

To test how the documentation renders use the Netlify Deploy Preview, especially when using Docusaurus-specific features. Or build it locally and test, using the make website-watch command.

info

Make sure to add any new pages to the appropriate sidebar file. Otherwise, the new page will not appear in the table of contents to the left.

General guidelines​

  • Try to order the documentation sections in the order that makes it easiest for the user to follow. That is, order the sections in the same order as the actual workflow used to accomplish the task. Use headings (sub-titles) to break up long documents, and make it easier to find a specific section.

  • You can use standard Docusaurus-specific features, which include MDX elements such as tabs and admonitions.

Terminology​

authentik names​

  • The product name authentik should always start with a lower-case "a" and end with a "k". Even if it is the first word in a sentence. :-)

  • Our company name is Authentik Security, Inc. but in non-legal documentation you can shorten it to Authentik Security.

Industry terms, technology, and other tools​

  • When referring to external tools, or an industry term or technology, always follow the exact capitalization that the product or company itself uses on their website, in their official documentation, or what the industry uses in consensus.

  • Try to avoid using abbreviations if possible.

  • Use acronyms where it makes sense (for commonly used terms like SAML or RBAC). If an acronym is less-known, spell it out in parentheses after the first use.

Writing style​

  • authentik documentation strives for a friendly, but not overly so, tone. It's ok to be a little bit conversational, and to address the reader in second person: "Next, you need to configure the log in settings."

  • Our documentation uses American English ("z" not "s").

  • Phrasing should almost always be in present tense and active voice:

    • DON'T: "The Applications page will be loaded."

    • DO: "The Applications page displays."

  • Phrasing should never blame the user, and should be subjective:

    • DON'T: "Never modify the default file."

    • DO: "We recommend that you do not modify the default file, because this can result in unexpected issues."

Formatting​

Formatting in documentation is important; it improves comprehension and readability, and allows the brain to more quickly determine what is a command or a configuration setting, what is a field name, or what is a variable.

  • When referring to UI elements or components in the authentik UI, such as field names, labels, etc., use bold text.

  • Use code format when referring to:

    • commands
    • file paths
    • directory names
    • code snippets (single line or a block of code)

  • For variables or placeholders use italic font for the variable, and use place-holder names that makes it obvious that the user needs to replace it.

    Example: https://company-domain/source/oauth/callback/source-slug

    When using variables in code snippets, make sure to specify if the value is something the user needs to define, is system-defined or generated.

  • When referring to authentik functionality and features, such as flows, stages, sources, or policies, do not capitalize and do not use bold or italic text. When possible link to the corresponding documentation.

Titles and headers​

  • Both titles and headers (H1, H2, H3) use sentence style capitalization, meaning that only the first word is capitalized. However, if the title or header includes a proper noun (name of a product, etc) then capitalize those words. Examples:
    • Configure your provider
    • Configure the Google Workspace provider