Conceptual topic
How to use this template: start with the markdown version of the template, either by copying the conceptual.tmpl.md file from our GitHub repo or downloading the template file using the following command:
wget https://raw.githubusercontent.com/goauthentik/authentik/main/website/developer-docs/docs/templates/conceptual.tmpl.md
Edit your markdown file as you work, reading this page for the descriptions of each section. You can build out a "stub file" with just headers, then gradually add content to each section. Use screenshots sparingly, only for complex UIs where it is difficult to describe a UI element with words. Refer to our General Guidelines for writing tips and authentik-specific rules.
Use a title that focuses on the feature, component, or technology you are writing about... for example, "About authentik polices" or "Understanding outposts". For conceptual docs, the verb in the title should indicate a concept, such as "About" or "Overview" or "Understanding", followed by the noun (the component or object you are writing about).
In this first section, immediately after the title, write one or two sentences about the feature, component, or technology. The following sections can help break up the content.
Common use cases (optional section)
In this optional section, provide some example use cases for the feature. Who would use it, WHY? If you mention HOW to use the feature, be sure to link off to the related procedural doc. Also share situations where users might NOT want to use the feature; for example, if the feature is intended for a specific environment.
Overview of feature/component
Dive deeper into explaining the concepts behind the feature/component.
Write about the feature/functionalilty from the user's perspective. What is this feature used for, why should they use it, are there situations where they should not use it?
Pro Tip: If you were writing the related procedural topic, and you found that you had a lot to say about the topic, this is exactly where that info would go (not crowded up at the top of the procedural topic!).
Cover anything the user needs to know about the feature. If there are Reference docs or a related procedural doc for this feature or component, be sure to link to them from this page.
Important considerations
List anything that might be critical for user to know, such as situations where this feature might not be ideal, or pre-configs that need to be set, etc.