From f4eecfe0821baabbbfcdee8b3c507a6985637aec Mon Sep 17 00:00:00 2001 From: forestcat-admin Date: Sat, 23 May 2026 22:40:09 +0200 Subject: [PATCH 1/5] fix setup instructions to use uv run --- docs/guides/writing-documentation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guides/writing-documentation.md b/docs/guides/writing-documentation.md index fd2681f..15fe254 100644 --- a/docs/guides/writing-documentation.md +++ b/docs/guides/writing-documentation.md @@ -38,7 +38,7 @@ Once you have cloned the repository, you can just edit a file in the [`docs/`](h ```shell uv venv uv pip install -r docs_requirements.txt - mkdocs serve + uv run mkdocs serve ``` When adding new content, you can use one of the templates below to get started: From b287b367e40b08fd45e37a55f711b7128d745148 Mon Sep 17 00:00:00 2001 From: forestcat-admin Date: Sun, 24 May 2026 02:29:55 +0200 Subject: [PATCH 2/5] add documentation-structure --- .../documentation-structure.md | 84 +++++++++++++++++-- 1 file changed, 78 insertions(+), 6 deletions(-) diff --git a/docs/concepts-and-configurations/documentation-structure.md b/docs/concepts-and-configurations/documentation-structure.md index 0ca89d3..dc4919f 100644 --- a/docs/concepts-and-configurations/documentation-structure.md +++ b/docs/concepts-and-configurations/documentation-structure.md @@ -5,12 +5,84 @@ summary: >- How our documentation is organized and what we do to balance ease of writing and understanding. --- -!!! info "ToDo" +!!! info "Info" - This section needs updating + If youre looking for a hands-on approach on how documentation is to be written you can find a [guide](../guides/writing-documentation.md) explaining the process. If youre unsure how to start you can find [templates](../guides/writing-documentation.md#3-addedit-your-markdown-file) there aswell. -- Docs should be english -- Guides are for step-by-step things - - Guides always have a "Goal" explicitly formulated -- Concepts and Configuration aim to make readers understand something in detail +## General Rules +Rules are formatting and writing decisions that apply to every document. Their goal is to provide a concise style across the whole documentation to keep the text easy to follow. +- All documents written in this project should be written in **english** to maximize the compatability across readers. +- The documentation structure is intended to be followed, while not being **enforced** to keep a low entry barier for documentation authors. +- Use features like _Admonitions_ given by markdown and the theme whenever they can help by increasing the readability and outlining important parts. For instructions on how to use these theme specific features please refer down to the _MkDocs shadcn_ documentation in the References section. + +## Document Scope +The scope for a concept document should be set to define responsibility and set boundaries to where that document applies. Especially lining out which services are affected by it. + +!!! note "Example" + + The scope for this document is aiming to convey the base concepts on how to structure concepts and configurations in this documentation. To provide high readability and a project wide concise structure that authors and readers can rely on. + +## Structuring Concepts + +!!! note "Goal" + + The goal for a concept is to provide the reader with a structured detailed explanation about an abstract concept, conveying why this concept was choosen and how it is intended to be used. + +### Describing the Concept +This section is a summary to give the reader a quick overview about the concept answering following questions: + +- What is this concept about? +- Why is this concept needed? +- What does this concept do? + +### Explaining the Concept +This section should be an in depth explanation about the concept, explaining the concept as detailed as needed for the reader to be able to transfer it into an implementation. The usage of graphs and diagrams is advised when they can help the reader to understand the concept better. + +### Referencing additional Sources +This section should include sources to other documentations, concepts and hand-on guides which the reader can look up to futher explore the defined concept. + + +## Structuring Configurations + +!!! note "Goal" + + A configuration document is intended to provide the reader with examples and best practices for configuring a specific item. It focuses on the technical implementation rather than an abstract concept. + +### Describing the Configuration +This section should give the reader a quick overview which configuration files are being described. + +### Providing the Configuration +Here should the author provide configuration sections or full templates. The configurations don't have to be fully complete, theyre rather a more structured view on which options are important and what to watch out for. + +### Discussing Authors Thoughts +A discussion why the author choose which configuration options and what to watch out for. Best practices should be taught here. This section can also link to outside sources. + +### Referencing Documentation +Here the author should provide upstream documentation which includes configuration options and further explanations why and how they are used. + + +## Structuring Guide + +!!! note "Goal" + + A guide intends to provide a hands-on approach to the reader which they can follow step-by-step to archive the guides defined goal. A good example for a guide can be found at [Writing Documentation](../guides/writing-documentation.md). + +### Defining the Goal +A guide should always have a goal defined in the beginning, using the _Admonition_ for a success box is highly advised. An example for a goal box is shown below: + +```markdown +!!! success "Goal" + How to setup, write its baseline documentation in ansible and deploy a service. +``` +### Instructing the Reader +A guide should always have numbered instruction steps which are easy to follow. Important notices and information should written in _Admonitions_ as direct notices from the author to the reader. Dangerous steps or options should use a `danger` Admonition. + +### Closing Up +A guide should be finished with steps and facts that can be checked by the reader to ensure that the guide worked as intended and all steps are completed correctly. + +## References +Here you can find useful documentation regarding writing documentation: + +- [MkDocs](https://www.mkdocs.org/user-guide/): This is the official mkdocs documentation, although it mostly explains configuring the mkdocs instance rather than explaining the usage. +- [MkDocs shadcn](https://asiffer.github.io/mkdocs-shadcn/): This is our theme for MkDocs which has its own syntax and quircks which can help writing more readable documentation From 8892f9e3bbe8f59e1d68694ef0a3dbf4c909eeac Mon Sep 17 00:00:00 2001 From: forestcat-admin Date: Sun, 24 May 2026 02:55:58 +0200 Subject: [PATCH 3/5] clarify the usage of the document scope and the differences between concept, configuration and guide --- .../documentation-structure.md | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-) diff --git a/docs/concepts-and-configurations/documentation-structure.md b/docs/concepts-and-configurations/documentation-structure.md index dc4919f..30d2ebe 100644 --- a/docs/concepts-and-configurations/documentation-structure.md +++ b/docs/concepts-and-configurations/documentation-structure.md @@ -16,13 +16,20 @@ Rules are formatting and writing decisions that apply to every document. Their g - The documentation structure is intended to be followed, while not being **enforced** to keep a low entry barier for documentation authors. - Use features like _Admonitions_ given by markdown and the theme whenever they can help by increasing the readability and outlining important parts. For instructions on how to use these theme specific features please refer down to the _MkDocs shadcn_ documentation in the References section. -## Document Scope -The scope for a concept document should be set to define responsibility and set boundaries to where that document applies. Especially lining out which services are affected by it. +## Defining a Document Scope +The scope for a document should be set to define responsibility and set boundaries to where that document applies. Especially lining out which services are affected by it. It **does not** need to be defined explicitly in the text, but should be kept in mind while writing. !!! note "Example" The scope for this document is aiming to convey the base concepts on how to structure concepts and configurations in this documentation. To provide high readability and a project wide concise structure that authors and readers can rely on. +We decide in this documentation between concepts, configurations and guides. Their separation should be clearified with folowing list: + +- **Concept:** A concept includes an abstract definition about a specific structure while not going into implementation details. +- **Configuration:** A configuration can be a follow up of a concept, explaining the specific implementation in a given environment. +- **Guide:** A guide is a step-by-step hands-on instruction for the reader to follow along. It can reference concepts and configurations. + + ## Structuring Concepts !!! note "Goal" From 2c814325584d71cd86816d837082f8ac8930c656 Mon Sep 17 00:00:00 2001 From: forestcat-admin Date: Wed, 27 May 2026 15:23:23 +0200 Subject: [PATCH 4/5] apply patch "0001-fixup-some-formulations.patch" --- .../documentation-structure.md | 34 +++++++++++++------ mkdocs.yml | 1 + 2 files changed, 24 insertions(+), 11 deletions(-) diff --git a/docs/concepts-and-configurations/documentation-structure.md b/docs/concepts-and-configurations/documentation-structure.md index 30d2ebe..a059b90 100644 --- a/docs/concepts-and-configurations/documentation-structure.md +++ b/docs/concepts-and-configurations/documentation-structure.md @@ -7,14 +7,14 @@ summary: >- !!! info "Info" - If youre looking for a hands-on approach on how documentation is to be written you can find a [guide](../guides/writing-documentation.md) explaining the process. If youre unsure how to start you can find [templates](../guides/writing-documentation.md#3-addedit-your-markdown-file) there aswell. + If youre looking for a hands-on approach on how documentation is to be written you can find a [guide](../guides/writing-documentation.md) explaining the process. If you're unsure how to start you can find [templates](../guides/writing-documentation.md#3-addedit-your-markdown-file) there aswell. ## General Rules -Rules are formatting and writing decisions that apply to every document. Their goal is to provide a concise style across the whole documentation to keep the text easy to follow. +These rules are general formatting and writing decisions that apply to every document. Their goal is to provide a concise style across the whole documentation to keep the text easy to follow. - All documents written in this project should be written in **english** to maximize the compatability across readers. - The documentation structure is intended to be followed, while not being **enforced** to keep a low entry barier for documentation authors. -- Use features like _Admonitions_ given by markdown and the theme whenever they can help by increasing the readability and outlining important parts. For instructions on how to use these theme specific features please refer down to the _MkDocs shadcn_ documentation in the References section. +- Use features like _Admonitions_ given by markdown and the theme whenever they can help by increasing the readability and outlining important parts. For instructions on how to use these theme specific features please refer down to the [MkDocs shadcn](https://asiffer.github.io/mkdocs-shadcn/) documentation. ## Defining a Document Scope The scope for a document should be set to define responsibility and set boundaries to where that document applies. Especially lining out which services are affected by it. It **does not** need to be defined explicitly in the text, but should be kept in mind while writing. @@ -23,11 +23,11 @@ The scope for a document should be set to define responsibility and set boundari The scope for this document is aiming to convey the base concepts on how to structure concepts and configurations in this documentation. To provide high readability and a project wide concise structure that authors and readers can rely on. -We decide in this documentation between concepts, configurations and guides. Their separation should be clearified with folowing list: +We generally distinguish between concepts, configurations and guides in this documentation. Their separation should be clarified with folowing list: -- **Concept:** A concept includes an abstract definition about a specific structure while not going into implementation details. +- **Concept:** A concept includes an abstract definition about a specific structure while not going into implementation details. It is a document intending to further the abstract understanding of structure. It can also go into detail about _why_ we do things a certain way. - **Configuration:** A configuration can be a follow up of a concept, explaining the specific implementation in a given environment. -- **Guide:** A guide is a step-by-step hands-on instruction for the reader to follow along. It can reference concepts and configurations. +- **Guide:** A guide is a step-by-step hands-on instruction for the reader to follow along. It can reference concepts and configurations. The important difference to the other two document types is that guides are goal oriented. Understanding how things work is secondary to achieving a specific thing. ## Structuring Concepts @@ -44,7 +44,7 @@ This section is a summary to give the reader a quick overview about the concept - What does this concept do? ### Explaining the Concept -This section should be an in depth explanation about the concept, explaining the concept as detailed as needed for the reader to be able to transfer it into an implementation. The usage of graphs and diagrams is advised when they can help the reader to understand the concept better. +This section should be an in depth explanation about the concept, explaining the concept as detailed as needed for the reader to be able to transfer it into an implementation. The usage of graphs and diagrams is advised when they can help the reader understand the concept better. ### Referencing additional Sources This section should include sources to other documentations, concepts and hand-on guides which the reader can look up to futher explore the defined concept. @@ -60,7 +60,7 @@ This section should include sources to other documentations, concepts and hand-o This section should give the reader a quick overview which configuration files are being described. ### Providing the Configuration -Here should the author provide configuration sections or full templates. The configurations don't have to be fully complete, theyre rather a more structured view on which options are important and what to watch out for. +Here the author should provide configuration sections or full templates. The configurations don't have to be fully complete, they're rather a more structured view on which options are important and what to watch out for. ### Discussing Authors Thoughts A discussion why the author choose which configuration options and what to watch out for. Best practices should be taught here. This section can also link to outside sources. @@ -69,7 +69,7 @@ A discussion why the author choose which configuration options and what to watch Here the author should provide upstream documentation which includes configuration options and further explanations why and how they are used. -## Structuring Guide +## Structuring Guides !!! note "Goal" @@ -78,15 +78,27 @@ Here the author should provide upstream documentation which includes configurati ### Defining the Goal A guide should always have a goal defined in the beginning, using the _Admonition_ for a success box is highly advised. An example for a goal box is shown below: +/// tab | Source + ```markdown !!! success "Goal" - How to setup, write its baseline documentation in ansible and deploy a service. + How to setup, write its baseline documentation in ansible, and deploy a service. ``` + +/// + +/// tab | Rendered + +!!! success "Goal" + How to setup, write its baseline documentation in ansible, and deploy a service. + +/// + ### Instructing the Reader A guide should always have numbered instruction steps which are easy to follow. Important notices and information should written in _Admonitions_ as direct notices from the author to the reader. Dangerous steps or options should use a `danger` Admonition. ### Closing Up -A guide should be finished with steps and facts that can be checked by the reader to ensure that the guide worked as intended and all steps are completed correctly. +While this section is optional, a guide should be finished with steps and facts that can be checked by the reader to ensure that the guide worked as intended and all steps are completed correctly. ## References Here you can find useful documentation regarding writing documentation: diff --git a/mkdocs.yml b/mkdocs.yml index 0ae452d..8158c75 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -9,6 +9,7 @@ markdown_extensions: - attr_list - codehilite - pymdownx.blocks.details + - pymdownx.blocks.tab - pymdownx.superfences: css_class: codehilite From d8d22b25053eecc2e974369095fbfa3679a4d31d Mon Sep 17 00:00:00 2001 From: forestcat-admin Date: Wed, 27 May 2026 20:40:54 +0200 Subject: [PATCH 5/5] fix multiple typos --- docs/concepts-and-configurations/documentation-structure.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/concepts-and-configurations/documentation-structure.md b/docs/concepts-and-configurations/documentation-structure.md index a059b90..f5f4a21 100644 --- a/docs/concepts-and-configurations/documentation-structure.md +++ b/docs/concepts-and-configurations/documentation-structure.md @@ -7,7 +7,7 @@ summary: >- !!! info "Info" - If youre looking for a hands-on approach on how documentation is to be written you can find a [guide](../guides/writing-documentation.md) explaining the process. If you're unsure how to start you can find [templates](../guides/writing-documentation.md#3-addedit-your-markdown-file) there aswell. + If you're looking for a hands-on approach on how documentation is to be written you can find a [guide](../guides/writing-documentation.md) explaining the process. If you're unsure how to start you can find [templates](../guides/writing-documentation.md#3-addedit-your-markdown-file) there aswell. ## General Rules These rules are general formatting and writing decisions that apply to every document. Their goal is to provide a concise style across the whole documentation to keep the text easy to follow. @@ -25,7 +25,7 @@ The scope for a document should be set to define responsibility and set boundari We generally distinguish between concepts, configurations and guides in this documentation. Their separation should be clarified with folowing list: -- **Concept:** A concept includes an abstract definition about a specific structure while not going into implementation details. It is a document intending to further the abstract understanding of structure. It can also go into detail about _why_ we do things a certain way. +- **Concept:** A concept includes an abstract definition about a specific structure while not going into implementation details. It is a document intending to further abstract the understanding of structure. It can also go into detail about _why_ we do things a certain way. - **Configuration:** A configuration can be a follow up of a concept, explaining the specific implementation in a given environment. - **Guide:** A guide is a step-by-step hands-on instruction for the reader to follow along. It can reference concepts and configurations. The important difference to the other two document types is that guides are goal oriented. Understanding how things work is secondary to achieving a specific thing.