website/docs: add more content about flows (goauthentik#10527)

* first pass

* reordered config options to match UI, added more

* tweaks

* add content for creating flows, add links to policies, update Style Guide

* tweaks

* procedurals, info about bindings

* stages stub file

* messy

* reorg procedurals

* tweak titles

* tweaks

* images

* images, remove old images

* tweak

* tweaks and fixes

* smaller image

* tweak

* had to rollback

* starting over after VS Code branch war

* fix links

* more tweaks

* Optimised images with calibre/image-actions

* fighting build break

* remove dupe image

* replace image with diagram code

* add image of UI, and reformat to look more like field names, not headings in the document

* Optimised images with calibre/image-actions

* new image

* rest of Jens' edits

* Optimised images with calibre/image-actions

* fix order of stages in example

* fixed arrows in image

---------

Signed-off-by: Tana M Berry <[email protected]>
Co-authored-by: Tana M Berry <[email protected]>
Co-authored-by: authentik-automation[bot] <135050075+authentik-automation[bot]@users.noreply.github.com>
Co-authored-by: Jens Langhammer <[email protected]>

website/developer-docs/docs/style-guide.mdx

@@ -2,19 +2,19 @@
 title: 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](./templates/index.md) when possible; they are already set up to follow may of the style guidelines below.
+The Style Guide provides guidelines to ensure that the authentik documentation is easy to read and uses similar phrasing, formatting, and tone.
+
+We appreciate contributions to our documentation; everything from fixing a typo to adding additional content to writing a completely new topic. To make the review and merging of your contributions faster and easier, please follow the [writing documentation](./writing-documentation.md) guidelines.
 
 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.
 
-To test how the documentation renders use the Netlify Deploy Preview, especially when using Docusaurus-specific features. Or [build it locally and test](./writing-documentation.md#set-up-your-local-build), using the `make website-watch` command.
+## General style guidelines
 
-:::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.
-:::
+-   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.
 
-## General guidelines
+-   Use headings (sub-titles) to break up long documents, and make it easier to find a specific section.
 
--   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.
+-   Add cross-reference links to related content whenever possible.
 
 -   You can use standard [Docusaurus-specific features](https://docusaurus.io/docs/next/markdown-features), which include MDX elements such as tabs and admonitions.
 
@@ -40,7 +40,7 @@ Make sure to add any new pages to the appropriate `sidebar` file. Otherwise, the
 
 -   Our documentation uses American English ("z" not "s").
 
--   Phrasing should almost always be in present tense and active voice:
+-   Use the present tense and active voice in almost all cases:
 
     -   DON'T: "The Applications page will be loaded."
 
@@ -56,12 +56,17 @@ Make sure to add any new pages to the appropriate `sidebar` file. Otherwise, the
 
 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.
 
+### Fonts and font styling
+
 -   When referring to UI elements or components in the authentik UI, such as field names, labels, etc., use **bold** text.
 
+-   When referring to internal components in authentik, like the policy engine, or blueprints, do not use any special formatting. Link to the relevant documentation when possible.
+
 -   Use `code` format when referring to:
 
     -   commands
     -   file paths
+    -   file names
     -   directory names
     -   code snippets (single line or a block of code)
 
@@ -77,5 +82,68 @@ Formatting in documentation is important; it improves comprehension and readabil
 
 -   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
+
+-   Make sure the title/header is descriptive, and tells the reader what that section is about. Try to avoid titles or headers like "Overview". Instead say "About authentik policies".
+
+-   Use the imperative verb form (not the gerund form) for procedural topics. For example, use "Configure your instance" instead of "Configuring your instance".
+
+### Examples
+
+When you want to show an example (say, a code snippet), use a new line, bold text, and a semi-colon, like this:
+
+    **Example**:
+    This expression policy uses an expression based on the user's name.
+    ```
+    if request.context["pending_user"].username == "marie":
+      return True
+    return False
+    ```
+
+### Notes and warnings
+
+Use the following convention for a note:
+
+```
+:::info
+Write your note here.
+:::
+```
+
+:::info
+Write your note here.
+:::
+
+For a warning, use this:
+
+```
+:::warning
+Write your note here.
+:::
+```
+
+:::warning
+Write your warning here.
+:::
+
+```
+
+```
+
+## Word choices
+
+-   **May** versus **might** versus **can**
+    Typically, the word "may" is not used in technical writing, because it implies permission (rather than ability) to do something. Instead use the word "can". Use "might" when the scenario could be different in certain environments. Be sparing with your use of "might"; this word implies unpredictability, not our favorite thing with software.
+
+    -   DON'T: "You may use an Expression policy to enforce MFA adherence."
+
+    -   DO: "You can use an Expression policy to enforce MFA adherence."
+
+    -   Do: "Values might differ depending on the source of the property mappings.""
+
+-   **Login**, **log in**, and **log in to**
+    As a descriptive term, use one word: "login". (The login panel.)
+    As a verb, use "log in", with two words. (This stage prompts the user to log in.)
+    As a verb with the proposition "to", use "log in to". (Log in to the application.)

website/developer-docs/docs/templates/combo.md

@@ -9,7 +9,7 @@ title: "Combination topic"
 wget https://raw.githubusercontent.com/goauthentik/authentik/main/website/developer-docs/docs/templates/combo.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#writing-guidelines) for writing tips and authentik-specific rules.
+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 [Style Guide](../style-guide.mdx) for writing tips and authentik-specific rules.
 :::
 
 For a combo topic, the title is typically the name of the feature ("Branding" or "Remote Access Control").

website/developer-docs/docs/templates/conceptual.md

@@ -9,7 +9,7 @@ title: "Conceptual topic"
 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](../writing-documentation#writing-guidelines) for writing tips and authentik-specific rules.
+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 [Style Guide](../style-guide.mdx) 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).

website/developer-docs/docs/templates/procedural.md

@@ -9,7 +9,7 @@ title: "Procedural topic"
 wget https://raw.githubusercontent.com/goauthentik/authentik/main/website/developer-docs/docs/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#writing-guidelines) for writing tips and authentik-specific rules.
+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 [Style Guide](../style-guide.mdx) for writing tips and authentik-specific rules.
 :::
 
 For a procedural topic, 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").

website/developer-docs/docs/templates/reference.md

@@ -9,7 +9,7 @@ title: "Reference topic"
 wget https://raw.githubusercontent.com/goauthentik/authentik/main/website/developer-docs/docs/templates/reference.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#writing-guidelines) for writing tips and authentik-specific rules.
+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 [Style Guide](../style-guide.mdx) for writing tips and authentik-specific rules.
 :::
 
 Create a title that specifies the component you are documenting. For example, "Group attributes".

website/developer-docs/docs/writing-documentation.md

@@ -2,7 +2,21 @@
 title: Writing documentation
 ---
 
-Writing documentation for authentik is a great way for both new and experienced users to improve and contribute to the project.
+Writing documentation for authentik is a great way for both new and experienced users to improve and contribute to the project. We appreciate contributions to our documentation; everything from fixing a typo to adding additional content to writing a completely new topic.
+
+Adhering to the following guidelines will help us get your PRs merged much easier and faster, with fewer edits needed.
+
+-   Ideally, when you are making contributions to the documentation, you should fork and clone our repo, then [build it locally](#set-up-your-local-build), so that you can test the docs and run the required linting and spell checkers before pushing your PR. While you can do much of the writing and editing within the GitHub UI, you cannot run the required linters from the GitHub UI.
+
+-   Please refer to our [Style Guide](./style-guide.mdx) for authentik documentation. Here you will learn important guidelines about not capitalizing authentik, how we format our titles and headers, and much more.
+
+-   Remember to use our [docs templates](./templates/index.md) when possible; they are already set up to follow our style guidelines, they make it a lot easier for you (no blank page frights!), and keeps the documentation structure and headings consistent.
+
+-   To test how the documentation renders you can build locally and then use the Netlify Deploy Preview, especially when using Docusaurus-specific features. You can also run the `make website-watch` command on your local build, to see the rendered pages as you make changes.
+
+-   Be sure to run the `make website` command on your local branch, before pushing the PR to the authentik repo. This command does important linting, and the build check in our repo will fail if the linting has not been done.
+
+-   For new entries, make sure to add any new pages to the appropriate `sidebar.js` file. Otherwise, the new page will not appear in the table of contents to the left.
 
 ## Set up your local build
 
@@ -12,7 +26,7 @@ Requirements:
 
 The docs and the code are in the same Github repo, at https://github.com/goauthentik/authentik, so if you have cloned the repo, you already have the docs.
 
-You can do local builds of the documentation to test your changes or review your new content, and to run the required `prettier` and linters before pushing your PR.
+You can do local builds of the documentation to test your changes or review your new content, and to run the required `make website` command (which runs `prettier` and other linters) before pushing your PR.
 
 The documentation site is situated in the `/website` folder of the repo.
 
@@ -28,22 +42,12 @@ The site is built using npm, below are some useful make commands:
 
 -   **Live editing**: `make website-watch`
 
-    For real time viewing of changes, as you make them.
+    For real-time viewing of changes, as you make them.
 
 :::info
 Be sure to run a formatting command before committing changes.
 :::
 
-## Writing guidelines
-
-Please refer to our [Style Guide](./style-guide.mdx) for authentik documentation. Here you will learn important guidelines about not capitalizing authentik, how we format our titles and headers, and much more.
-
-Whenever possible, use one of our [doc templates](./templates/index.md). This makes it a lot easier for you (no blank page frights!) and keeps the documentation consistent.
-
-Make sure to add the new pages to the appropriate place in `/website/sidebars.js`. Otherwise, the content will not appear in the table of contents to the left.
-
-Following the guidelines will make getting your PRs merged much easier and faster, with fewer edits needed. We appreciate our community contributors helping us keep the Docs consistent, easy-to-use, and high quality.
-
 ## Documentation for Integrations
 
 In addition to following the [Style Guide](./style-guide.mdx) please review the following guidelines.