From 9bdda11c88a529c866eeaa8c9b534cec449b8dd0 Mon Sep 17 00:00:00 2001 From: Tana M Berry Date: Thu, 10 Aug 2023 10:21:53 -0500 Subject: [PATCH] website/docs: added conceptual template (#6518) added conceptual template Co-authored-by: Tana Berry --- .../docs/templates/conceptual.md | 19 +++++++++++++++++++ .../developer-docs/docs/templates/index.md | 4 ++-- website/sidebarsDev.js | 5 ++++- 3 files changed, 25 insertions(+), 3 deletions(-) create mode 100644 website/developer-docs/docs/templates/conceptual.md diff --git a/website/developer-docs/docs/templates/conceptual.md b/website/developer-docs/docs/templates/conceptual.md new file mode 100644 index 000000000..d58058a47 --- /dev/null +++ b/website/developer-docs/docs/templates/conceptual.md @@ -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. diff --git a/website/developer-docs/docs/templates/index.md b/website/developer-docs/docs/templates/index.md index 9645e706d..654660f6e 100644 --- a/website/developer-docs/docs/templates/index.md +++ b/website/developer-docs/docs/templates/index.md @@ -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. -- **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! diff --git a/website/sidebarsDev.js b/website/sidebarsDev.js index 47361ce97..30cbe3922 100644 --- a/website/sidebarsDev.js +++ b/website/sidebarsDev.js @@ -69,7 +69,10 @@ module.exports = { type: "doc", id: "docs/templates/index", }, - items: ["docs/templates/procedural"], + items: [ + "docs/templates/procedural", + "docs/templates/conceptual", + ], }, ], },