website/dev-docs: more raw templates, fixed wget link (#6778)
* fixed broken link to raw template * removed problematic link to concept topic * added raw concept topic * added raw template for reference topic * added How to use section * fixed url for raw * Update website/developer-docs/docs/templates/procedural.md Co-authored-by: Jens L. <jens@goauthentik.io> Signed-off-by: Tana M Berry <tanamarieberry@yahoo.com> * Update website/developer-docs/docs/templates/conceptual.tmpl.md Signed-off-by: Tana M Berry <tanamarieberry@yahoo.com> * fixed empty file * linter issue * nother typo --------- Signed-off-by: Tana M Berry <tanamarieberry@yahoo.com> Co-authored-by: Tana Berry <tana@goauthentik.io> Co-authored-by: Jens L. <jens@goauthentik.io>
This commit is contained in:
Tana M Berry
GitHub
parent
eeb124e869
commit
8ef33e0285
|
|
@ -2,6 +2,16 @@
|
|||
title: "Conceptual topic"
|
||||
---
|
||||
|
||||
:::info
|
||||
**How to use this template**: start with the markdown version of the template, either by copying the [`conceptual.tmpl.md`](https://github.com/goauthentik/authentik/tree/main/website/developer-docs/docs/templates) 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](../writing-documentation#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.
|
||||
|
|
@ -14,6 +24,12 @@ In this optional section, provide some example use cases for the feature. Who wo
|
|||
|
||||
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 for this feature or component, be sure to link to them from this page.
|
||||
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.
|
||||
|
|
|
|||
21
website/developer-docs/docs/templates/conceptual.tmpl.md
vendored
Normal file
21
website/developer-docs/docs/templates/conceptual.tmpl.md
vendored
Normal file
|
|
@ -0,0 +1,21 @@
|
|||
---
|
||||
title: "Markdown template: conceptual"
|
||||
---
|
||||
|
||||
Write a few sentences introducing the feature/component/technology.
|
||||
|
||||
:::info
|
||||
if needed, use this syntax to add a note (info) or warning (warning)
|
||||
:::
|
||||
|
||||
## Common use cases
|
||||
|
||||
Provide a few use cases, with examples/scenarios when possible.
|
||||
|
||||
## About feature x
|
||||
|
||||
Provide more conceptual details.
|
||||
|
||||
##Important considerations
|
||||
|
||||
List anything users should know before implementing the feature/technology.
|
||||
|
|
@ -3,16 +3,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:
|
||||
**How to use this template**: start with the markdown version of the template, either by copying the [`procedural.tmpl.md`](https://github.com/goauthentik/authentik/tree/main/website/developer-docs/docs/templates) 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/templates/procedural.tmpl.md
|
||||
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#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").
|
||||
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").
|
||||
|
||||
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.
|
||||
|
||||
|
|
@ -24,7 +24,7 @@ In this section, inform the reader of anything they need to do, or have configur
|
|||
|
||||
If the task is quite long or complex, it might be good to add a bullet list of the main steps, or even a diagram of the workflow, just so that the reader can first familairize themselves with the 50,000 meter view before they dive into the detailed steps.
|
||||
|
||||
## first several group steps
|
||||
## First several group steps
|
||||
|
||||
If the task involves a lot of steps, try to group them into similar steps and have a Head3 or Head4 title for each group.
|
||||
|
||||
|
|
@ -32,16 +32,16 @@ In this section, help the reader get oriented... where do they need to be (i.e.
|
|||
|
||||
Have a separate paragraph for each step.
|
||||
|
||||
Start instructions with the desired outcome, followed by the instructions.
|
||||
Start instructions with the desired goal, followed by the instructions. For example, in this sentence we first read the goal (to define a new port) and then we see the instructions: "To define a new port number, navigate to the Admin interface, and then to the **Settings** tab."
|
||||
|
||||
EXAMPLE: To define a new port number, navigate to the Admin interface, and then to the **Settings** tab.
|
||||
|
||||
## next step of grouped steps
|
||||
## Next step of grouped steps (if a second group is needed)
|
||||
|
||||
Continue with the steps...
|
||||
|
||||
Use screenshots sparingly, only for complex UIs where it is difficult to describe a UI element with words.
|
||||
|
||||
## verify the steps
|
||||
Provide as many code snippets and examples as needed.
|
||||
|
||||
Whenever possible, it is useful to add verification steps at the end of a procedural topic. For example, if the procedural was about installing a product, use this section to tell them how they can verify that the install was successful.
|
||||
## Verify the steps
|
||||
|
||||
Use a heading such as "Verify your installation" or "Verify successful configuration". Whenever possible, it is useful to add verification steps at the end of a procedural topic. For example, if the procedural was about installing a product, use this section to tell them how they can verify that the install was successful.
|
||||
|
|
|
|||
|
|
@ -2,17 +2,25 @@
|
|||
title: "Reference topic"
|
||||
---
|
||||
|
||||
:::info
|
||||
**How to use this template**: start with the markdown version of the template, either by copying the [`reference.tmpl.md`](https://github.com/goauthentik/authentik/tree/main/website/developer-docs/docs/templates) 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/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#general-guidelines) for writing tips and authentik-specific rules.
|
||||
:::
|
||||
|
||||
Create a title that specifies the component you are documenting. For example, "Group attributes".
|
||||
|
||||
Provide a sentence or two about the topic.
|
||||
|
||||
Reference documentation provides details, values, syntax, etc., about specific programming elements.
|
||||
|
||||
The most common type of reference documentation is for REST APIs; the request syntax, a successful response, any parameters such as query, header, or request body parameters, and possible http status codes.
|
||||
|
||||
Other types of reference content include lists of functions, parameters, event actions, and attributes.
|
||||
|
||||
## Overview
|
||||
|
||||
Provide a sentence or two about the topic.
|
||||
Other types of reference content include lists of functions, parameters, object properties, event actions, and attributes.
|
||||
|
||||
## Head 2
|
||||
|
||||
|
|
@ -22,10 +30,10 @@ Use tables, bullet lists, Head3s... whatever you need to clearly present the val
|
|||
|
||||
Be sure to use a sentence after every heading, to explain what the section is about, how the values are used, etc.
|
||||
|
||||
## Head 3 (optional, if needed)
|
||||
### Head 3 (optional, if needed)
|
||||
|
||||
Add a sentence explaining the following grouping.
|
||||
|
||||
## Head 3 (optional, if needed)
|
||||
### Head 3 (optional, if needed)
|
||||
|
||||
Add a sentence explaining the following grouping.
|
||||
|
|
|
|||
19
website/developer-docs/docs/templates/reference.tmpl.md
vendored
Normal file
19
website/developer-docs/docs/templates/reference.tmpl.md
vendored
Normal file
|
|
@ -0,0 +1,19 @@
|
|||
---
|
||||
title: "Markdown template: reference"
|
||||
---
|
||||
|
||||
Write a few sentences introducing the feature/component/technology, and state that this page contains refeerence materials.
|
||||
|
||||
:::info
|
||||
if needed, use this syntax to add a note (info) or warning (warning)
|
||||
:::
|
||||
|
||||
## Head 2
|
||||
|
||||
After a brief description of this section, list the reference values.
|
||||
|
||||
Consider using a table if that is cleaner looking.
|
||||
|
||||
### Head 3 (optional, if needed)
|
||||
|
||||
After a brief description of this section, list the reference values.
|
||||
Reference in a new issue