From 5ea67398ae8a41cf67dff0740b5780aa3ee69df2 Mon Sep 17 00:00:00 2001 From: Tana M Berry Date: Wed, 6 Sep 2023 08:04:35 -0500 Subject: [PATCH] website/dev-docs: add raw markdown template (#6768) * add raw markdown template * changed to truly raw markdown file * fix download link Signed-off-by: Jens Langhammer --------- Signed-off-by: Jens Langhammer Co-authored-by: Tana Berry Co-authored-by: Jens Langhammer --- .../developer-docs/docs/templates/index.md | 2 +- .../docs/templates/procedural.md | 10 ++++++ .../docs/templates/procedural.tmpl.md | 35 +++++++++++++++++++ .../docs/writing-documentation.md | 4 +-- 4 files changed, 48 insertions(+), 3 deletions(-) create mode 100644 website/developer-docs/docs/templates/procedural.tmpl.md diff --git a/website/developer-docs/docs/templates/index.md b/website/developer-docs/docs/templates/index.md index 654660f6e..661e3d87f 100644 --- a/website/developer-docs/docs/templates/index.md +++ b/website/developer-docs/docs/templates/index.md @@ -10,6 +10,6 @@ The most common types are: - [**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 functions, or most commmonly APIs. +- [**Reference**](./reference.md): 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/developer-docs/docs/templates/procedural.md b/website/developer-docs/docs/templates/procedural.md index 53b3502cb..04be51ff0 100644 --- a/website/developer-docs/docs/templates/procedural.md +++ b/website/developer-docs/docs/templates/procedural.md @@ -2,6 +2,16 @@ title: "Procedural topic" --- +:::info +**How to use this template**: start with the [markdown version](./procedural.tmpl.md) of the template, either copying the file from the local repo or download the template file using the following command: + +``` +wget https://raw.githubusercontent.com/goauthentik/authentik/main/website/developer-docs/docs/templates/templates/procedural.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](../writing-documentation#general-guidelines) for writing tips and authentik-specific rules. +::: + Use a title that focuses on the task you are writing about... for example, "Add a new Group" or "Edit user profiles". For procedural docs, there should be a verb in the title, and usually the noun (the component or object you are working on). For the title (and all headings) use the infinitive form of the verb (i.e. "add") not the gerund form (i.e. "adding"). In this first section, right after the title, write one or two sentences about the task. Keep it brief; if it goes on too long, then create a separate conceptual topic, in a separate `.md` file. We don't want readers to have to scroll through paragraphs of conceptual info before they get to Step 1. diff --git a/website/developer-docs/docs/templates/procedural.tmpl.md b/website/developer-docs/docs/templates/procedural.tmpl.md new file mode 100644 index 000000000..641ebb43c --- /dev/null +++ b/website/developer-docs/docs/templates/procedural.tmpl.md @@ -0,0 +1,35 @@ +--- +title: "Markdown template: procedural" +--- + +add brief description of the feature/functionality + +:::info +if needed, use this syntax to add a note (info) or warning (warning) +::: + +## Prerequisites + +bullet list of pre-reqs + +## Overview of steps/workflow + +describe the 50,000 meter view before they dive into the detailed steps, using a bullet list of the main steps, or even a diagram of the workflow. + +## first several group steps + +1. first step + +2. second step + +3. third step + +if you need a tabbed section to represent diff processes or code snippets for diff install environments, use an MDX tabbed component. + +## next step of grouped steps, if needed + +Continue with the steps... + +## verify the steps + +add verification steps diff --git a/website/developer-docs/docs/writing-documentation.md b/website/developer-docs/docs/writing-documentation.md index d8c51559c..cd874207c 100644 --- a/website/developer-docs/docs/writing-documentation.md +++ b/website/developer-docs/docs/writing-documentation.md @@ -52,8 +52,8 @@ Be sure to run the formatter before committing changes. - When referring to UI text or UI components in authentik, use **bold** text. - When referring to other objects in authentik code or functionality, use _cursive_ text, and link to the corresponding documentation if possible. - When referring to external tools, give an example how to use the tools or explain how the user can use them. -- Make sure to add the documentation to add to the sidebar, if adding a new page. -- Test how the documentation renders using the Netlify Deploy Preview, especially when using Docusaurus-specific features. +- Make sure to add the documentation to the sidebar, if adding a new page. +- Test how the documentation renders using the Netlify Deploy Preview, especially when using Docusaurus-specific features. Or build it locally and test, using the `make website-watch` command. If you find any documentation that doesn't match these guidelines, feel free to either open an [Issue](https://github.com/goauthentik/authentik/issues) or a [PR](https://github.com/goauthentik/authentik/pulls) so they can be fixed.