website/docs: added conceptual template (#6518)

added conceptual template

Co-authored-by: Tana Berry <tana@goauthentik.io>
This commit is contained in:
Tana M Berry 2023-08-10 10:21:53 -05:00 committed by GitHub
parent 8fb0d7be2a
commit 9bdda11c88
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
3 changed files with 25 additions and 3 deletions

View File

@ -0,0 +1,19 @@
---
title: "Conceptual topic"
---
Use a title that focuses on the feature, component, or technolgy 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 technolgy. 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.
> 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 for this feature or component, be sure to link to them from this page.

View File

@ -8,8 +8,8 @@ The most common types are:
- [**Procedural**](./procedural.md): these are How To docs, the HOW information, with step-by-step instructions for accomplishing a task. This is what most people are looking for when they open the docs... and best practice is to separate the procedural docs from long, lengthy conceptual or reference docs. - [**Procedural**](./procedural.md): these are How To docs, the HOW information, with step-by-step instructions for accomplishing a task. This is what most people are looking for when they open the docs... and best practice is to separate the procedural docs from long, lengthy conceptual or reference docs.
- **Conceptual**: these docs provide the WHY information, and explain when to use a feature (or when not to!), and general concepts behind the feature or functioanlity. - [**Conceptual**](./conceptual.md): these docs provide the WHY information, and explain when to use a feature (or when not to!), and general concepts behind the feature or functionality.
- **Reference**: this is typically tables or lists of reference information, such as configuration values, or most commmonly APIs. - **Reference**: this is typically tables or lists of reference information, such as configuration values, or functions, or most commmonly APIs.
We have templates for the different types, to make it super-easy for whomever wants to contribute some documentation! We have templates for the different types, to make it super-easy for whomever wants to contribute some documentation!

View File

@ -69,7 +69,10 @@ module.exports = {
type: "doc", type: "doc",
id: "docs/templates/index", id: "docs/templates/index",
}, },
items: ["docs/templates/procedural"], items: [
"docs/templates/procedural",
"docs/templates/conceptual",
],
}, },
], ],
}, },