From 71c6090c4bcf2bf9fbb9885b84e2919f074a589d Mon Sep 17 00:00:00 2001
From: Tiara Lena Hock <hock@b1-systems.de>
Date: Tue, 31 Mar 2026 18:00:44 +0200
Subject: [PATCH 1/8] Docs: Create Documentation Workflow

---
 .gitignore                                  |   3 +-
 docs/contributing/documentation_workflow.md | 127 ++++++++++++++++++++
 2 files changed, 129 insertions(+), 1 deletion(-)
 create mode 100644 docs/contributing/documentation_workflow.md

diff --git a/.gitignore b/.gitignore
index e1c6a07..9335d39 100644
--- a/.gitignore
+++ b/.gitignore
@@ -12,11 +12,12 @@ docs/**/.media
 docs/**/_static
 docs/**/assets
 
-# Section directories - aggregated content is ignored, index.md is tracked
+# Section directories - aggregated content is ignored, index.md and selected files are tracked
 docs/contributing/**
 !docs/contributing/index.md
 !docs/contributing/documentation/
 !docs/contributing/documentation/**
+!docs/contributing/documentation_workflow.md
 docs/explanation/**
 !docs/explanation/index.md
 !docs/explanation/documentation/
diff --git a/docs/contributing/documentation_workflow.md b/docs/contributing/documentation_workflow.md
new file mode 100644
index 0000000..cb1948d
--- /dev/null
+++ b/docs/contributing/documentation_workflow.md
@@ -0,0 +1,127 @@
+---
+title: Documentation Workflow
+description: How to Contribute Documentation to Gardenlinux
+order: 1
+---
+
+# Documenting Gardenlinux
+
+This guide will provide you a detailed overview over everything you need to know
+to support our efforts in documenting the Gardenlinux project.
+
+## When Is Documentation Necessary?
+
+Documentation is always necessary when a piece of software, a process or
+information is touched that has implications for other people. May they be
+internal or external contributors, users or decision makers.
+
+## What Should Be Documented?
+
+In the context of this Documentation Hub, anything that has implication to the
+"outside". Meaning other users, operators, developers or decision makers needs
+to be documented accordingly.
+
+This includes, but is not limited to:
+
+- Usage of Gardenlinux and any supporting tool
+- Features and components of the project
+- Ways to contribute and where to find help
+- Information about where to submit security incidents
+- Information about who is developing the project
+
+Of course this does not apply to purely internal changes like code cleanup
+contributions or similar that have no outside effect.
+
+## Who Is Responsible for Maintaining Documentation?
+
+The question of _"who is responsible?"_ can be split into two camps: The
+contributors and a documentation lead.
+
+### Contributors
+
+Contributors are defined as individuals, groups or organisation that submit code
+or non-code contributions to the project. These should, in addition to their
+submission, document their changes with appropriate changes to any relevant
+pieces of documentation. This applies to _any contribution_ if the change is
+relevant for others.
+
+For example:
+
+1. A person introduces a new feature to Gardenlinux and opens a Pull Request
+2. After their PR is approved, they are greenlit to open a PR in the `docs-ng`
+   branch of the code repository in which they document their new feature.
+3. The PR will be reviewed by a maintainer or the documentation lead on duty.
+4. After both are greenlit, both PRs are merged.
+
+### The Documentation Lead
+
+This is a more or less informal position that is quite common in many projects:
+One maintainer/developer who is responsible for handling the documentation hub
+and enforcing style and quality standards according to written design documents.
+
+This can be a liaison to a formal documentation team who is briefed on the
+project and works closely with the development team, a team member that is
+permanently appointed to or volunteers for this position, or a rotating position
+that anyone in the team may take on for a set amount of time.
+
+However this may be implemented it is important to stress that _**documentation
+is a team effort**_.
+
+The responsibilities of this person are:
+
+- Evaluating whether a contribution requires documentation & what scope that
+  documentation needs to be
+- Making sure that documentation is written and put in the correct space
+- Ensuring that the documentation pipeline is running and the documentation
+  website is accessible
+
+## The Review Process
+
+Any changes to documentation will be reviewed by maintainers for the quality
+criteria mentioned below. Only after the review is sucessful will the changes be
+merged. The review validates:
+
+- **Technical accuracy and sufficient depth**: The document matches implemented
+  behaviour and guides are executable.
+- **Completeness**: All affected changes are documented.
+- **Readability**: The documentation is free of typos and grammatical errors.
+- **Style and Inclusivity**: Language follows the project's expectations and
+  quality criteria, all images have appropriate alt text descriptions for people
+  using screen readers.
+
+In cases where there is a Documentation Lead, this person must review changes to
+documentation for their adherence to the project's quality markers.
+
+In cases where there is **no** dedicated Documentation Lead, documentation
+changes must be reviewed by other team members and tweaked according to their
+feedback until unanimous agreement is reached.
+
+## Quality Markers
+
+All documentation should have a professional and inclusive tone. Gender-neutral
+language (like they/them or role based nouns like "maintainer", "developer" or
+"user") should be used. Language specific idioms common amongst native speakers
+should be avoided and project specific abbreviations should always link to their
+respective Glossar section.
+
+Documentation should go into appropriate detail for the intended autience (i.e.
+Users or Developers) and not omit any details or become vague when talking about
+specific topics.
+
+If a feature is not yet implemented or there are currently known bugs or Issues,
+a "Known Issues" section should be appended to the bottom of the document
+listing these issues and their corresponding GitHub issue if applicable.
+
+Include expected output or other steps which the reader can use to verify
+operation outcomes in any instructional guides.
+
+Use examples liberally across the documentation for any document that advises
+readers to action.
+
+## Version Compatibility
+
+Features that only apply to a specific versions of gardenlinux or supporting
+tools should be marked as such using admonishments.
+
+Breaking changes between version should be indicated in a appropriately colored
+warning or info box at the top of the document.

From 8f9f3ebc7e1de49809c28fc284a62dcec9f00a20 Mon Sep 17 00:00:00 2001
From: Tiara Lena Hock <hock@b1-systems.de>
Date: Wed, 8 Apr 2026 10:54:37 +0200
Subject: [PATCH 2/8] Docs: Remove mentions of the docs-ng branches & fix typos

Signed-off-by: Tiara Lena Hock <hock@b1-systems.de>
---
 docs/contributing/documentation_workflow.md | 34 +++++++++++----------
 1 file changed, 18 insertions(+), 16 deletions(-)

diff --git a/docs/contributing/documentation_workflow.md b/docs/contributing/documentation_workflow.md
index cb1948d..3b23260 100644
--- a/docs/contributing/documentation_workflow.md
+++ b/docs/contributing/documentation_workflow.md
@@ -34,24 +34,26 @@ contributions or similar that have no outside effect.
 
 ## Who Is Responsible for Maintaining Documentation?
 
-The question of _"who is responsible?"_ can be split into two camps: The
+The question of _"who is responsible?"_ can be split into two roles: The
 contributors and a documentation lead.
 
 ### Contributors
 
-Contributors are defined as individuals, groups or organisation that submit code
-or non-code contributions to the project. These should, in addition to their
-submission, document their changes with appropriate changes to any relevant
-pieces of documentation. This applies to _any contribution_ if the change is
-relevant for others.
+Contributors are defined as individuals, groups or organisations that submit
+code or non-code contributions to the project. These should, in addition to
+their submission, document their changes with appropriate changes to any
+relevant pieces of documentation. This applies to _any contribution_ if the
+change is relevant for others.
 
 For example:
 
 1. A person introduces a new feature to Gardenlinux and opens a Pull Request
-2. After their PR is approved, they are greenlit to open a PR in the `docs-ng`
-   branch of the code repository in which they document their new feature.
-3. The PR will be reviewed by a maintainer or the documentation lead on duty.
-4. After both are greenlit, both PRs are merged.
+2. A maintainer reviews said feature and advises the contributor to write
+   documentation for it
+3. Said documentation will reviewed by the maintainer in question or the
+   documentation lead if applicable
+4. If both the code and the documentation both fulfill their respective quality
+   markers, the PR is merged
 
 ### The Documentation Lead
 
@@ -71,15 +73,15 @@ The responsibilities of this person are:
 
 - Evaluating whether a contribution requires documentation & what scope that
   documentation needs to be
-- Making sure that documentation is written and put in the correct space
+- Making sure that documentation is written and put in the correct place
 - Ensuring that the documentation pipeline is running and the documentation
   website is accessible
 
 ## The Review Process
 
 Any changes to documentation will be reviewed by maintainers for the quality
-criteria mentioned below. Only after the review is sucessful will the changes be
-merged. The review validates:
+criteria mentioned below. Only after the review is successful will the changes
+be merged. The review validates:
 
 - **Technical accuracy and sufficient depth**: The document matches implemented
   behaviour and guides are executable.
@@ -102,9 +104,9 @@ All documentation should have a professional and inclusive tone. Gender-neutral
 language (like they/them or role based nouns like "maintainer", "developer" or
 "user") should be used. Language specific idioms common amongst native speakers
 should be avoided and project specific abbreviations should always link to their
-respective Glossar section.
+respective Glossary section.
 
-Documentation should go into appropriate detail for the intended autience (i.e.
+Documentation should go into appropriate detail for the intended audience (i.e.
 Users or Developers) and not omit any details or become vague when talking about
 specific topics.
 
@@ -120,7 +122,7 @@ readers to action.
 
 ## Version Compatibility
 
-Features that only apply to a specific versions of gardenlinux or supporting
+Features that only apply to a specific versions of Gardenlinux or supporting
 tools should be marked as such using admonishments.
 
 Breaking changes between version should be indicated in a appropriately colored

From 8f49d634bdb6d7f5258ec2ff19d58090051c36b8 Mon Sep 17 00:00:00 2001
From: Tiara Lena Hock <hock@b1-systems.de>
Date: Wed, 8 Apr 2026 15:04:57 +0200
Subject: [PATCH 3/8] Docs: Add separate quality markers and finish doc
 workflow

Signed-off-by: Tiara Lena Hock <hock@b1-systems.de>
---
 .../documentation_workflow.md                 |  96 ++++-----
 docs/contributing/documentation/index.md      |  21 +-
 .../documentation/writing_good_docs.md        | 185 ++++++++++++++++++
 3 files changed, 256 insertions(+), 46 deletions(-)
 rename docs/contributing/{ => documentation}/documentation_workflow.md (57%)
 mode change 120000 => 100644 docs/contributing/documentation/index.md
 create mode 100644 docs/contributing/documentation/writing_good_docs.md

diff --git a/docs/contributing/documentation_workflow.md b/docs/contributing/documentation/documentation_workflow.md
similarity index 57%
rename from docs/contributing/documentation_workflow.md
rename to docs/contributing/documentation/documentation_workflow.md
index 3b23260..136b15b 100644
--- a/docs/contributing/documentation_workflow.md
+++ b/docs/contributing/documentation/documentation_workflow.md
@@ -6,8 +6,12 @@ order: 1
 
 # Documenting Gardenlinux
 
-This guide will provide you a detailed overview over everything you need to know
-to support our efforts in documenting the Gardenlinux project.
+This guide will provide you with a detailed overview over everything you need to
+know to support our efforts in documenting the Gardenlinux project.
+
+If you would like to know what markers we use to determine if submitted
+documentation is good, please check our guide about
+[Document Quality Markers](./writing_good_docs.md)
 
 ## When Is Documentation Necessary?
 
@@ -50,16 +54,16 @@ For example:
 1. A person introduces a new feature to Gardenlinux and opens a Pull Request
 2. A maintainer reviews said feature and advises the contributor to write
    documentation for it
-3. Said documentation will reviewed by the maintainer in question or the
+3. Said documentation will be reviewed by the maintainer in question or the
    documentation lead if applicable
-4. If both the code and the documentation both fulfill their respective quality
-   markers, the PR is merged
+4. If both the code and the documentation fulfill their respective
+   [quality markers](./writing_good_docs.md), the PR is merged
 
 ### The Documentation Lead
 
 This is a more or less informal position that is quite common in many projects:
 One maintainer/developer who is responsible for handling the documentation hub
-and enforcing style and quality standards according to written design documents.
+and enforcing [quality standards](./writing_good_docs.md).
 
 This can be a liaison to a formal documentation team who is briefed on the
 project and works closely with the development team, a team member that is
@@ -77,53 +81,55 @@ The responsibilities of this person are:
 - Ensuring that the documentation pipeline is running and the documentation
   website is accessible
 
-## The Review Process
+### Documentation Ownership
 
-Any changes to documentation will be reviewed by maintainers for the quality
-criteria mentioned below. Only after the review is successful will the changes
-be merged. The review validates:
+Documentation ownership depends on the scope:
 
-- **Technical accuracy and sufficient depth**: The document matches implemented
-  behaviour and guides are executable.
-- **Completeness**: All affected changes are documented.
-- **Readability**: The documentation is free of typos and grammatical errors.
-- **Style and Inclusivity**: Language follows the project's expectations and
-  quality criteria, all images have appropriate alt text descriptions for people
-  using screen readers.
+- **Subproject documentation** (e.g., builder, python-gardenlinux-lib): Owned
+  and maintained by the contributors most active on that subproject if no formal
+  assignment to said project exist
+- **Documentation hub content** (e.g., these contributing guides): Owned by the
+  Documentation Lead if that role exists, otherwise by the core team
+  collectively
 
-In cases where there is a Documentation Lead, this person must review changes to
-documentation for their adherence to the project's quality markers.
-
-In cases where there is **no** dedicated Documentation Lead, documentation
-changes must be reviewed by other team members and tweaked according to their
-feedback until unanimous agreement is reached.
+## How to Submit Documentation Changes
 
-## Quality Markers
+To contribute documentation to Gardenlinux:
 
-All documentation should have a professional and inclusive tone. Gender-neutral
-language (like they/them or role based nouns like "maintainer", "developer" or
-"user") should be used. Language specific idioms common amongst native speakers
-should be avoided and project specific abbreviations should always link to their
-respective Glossary section.
+1. **Create a branch** named descriptively ideally with a `docs/` prefix
+2. **Make your changes** following the [quality markers](./writing_good_docs.md)
+3. **Add frontmatter** to your markdown files according to the
+   [technical reference](/reference/documentation/technical.md)
+4. **Test your changes** locally by running the documentation server
+5. **Open a Pull Request** with:
+   - Clear description of what documentation was added/changed
+   - Reference to any related code changes or issues
+   - Screenshots if visual changes were made
+6. **Address review feedback** from maintainers or the Documentation Lead
 
-Documentation should go into appropriate detail for the intended audience (i.e.
-Users or Developers) and not omit any details or become vague when talking about
-specific topics.
-
-If a feature is not yet implemented or there are currently known bugs or Issues,
-a "Known Issues" section should be appended to the bottom of the document
-listing these issues and their corresponding GitHub issue if applicable.
+## The Review Process
 
-Include expected output or other steps which the reader can use to verify
-operation outcomes in any instructional guides.
+Any changes to documentation will be reviewed by maintainers for the criteria
+listed in the [quality criteria guide](./writing_good_docs.md). Only after the
+review is successful will the changes be merged.
 
-Use examples liberally across the documentation for any document that advises
-readers to action.
+In cases where there is a Documentation Lead, this person must review changes to
+documentation for their adherence to the project's quality markers.
 
-## Version Compatibility
+In cases where there is **no** dedicated Documentation Lead, documentation
+changes must be reviewed by other team members and tweaked according to their
+feedback until unanimous agreement is reached.
 
-Features that only apply to a specific versions of Gardenlinux or supporting
-tools should be marked as such using admonishments.
+The review validates:
 
-Breaking changes between version should be indicated in a appropriately colored
-warning or info box at the top of the document.
+- **Technical accuracy and sufficient depth**: The document matches implemented
+  behaviour, commands are correct and tested
+- **Completeness**: All affected changes are documented, prerequisites are
+  stated, next steps are provided
+- **Readability**: The documentation is free of typos and grammatical errors,
+  has clear structure and flows logically
+- **Style and Inclusivity**: Language follows the project's
+  [quality criteria](./writing_good_docs.md), all images have appropriate alt
+  text descriptions
+- **Maintainability**: Documentation follows single source of truth principle,
+  ownership is clear, no unnecessary duplication
diff --git a/docs/contributing/documentation/index.md b/docs/contributing/documentation/index.md
deleted file mode 120000
index aa5f121..0000000
--- a/docs/contributing/documentation/index.md
+++ /dev/null
@@ -1 +0,0 @@
-../../tutorials/documentation/index.md
\ No newline at end of file
diff --git a/docs/contributing/documentation/index.md b/docs/contributing/documentation/index.md
new file mode 100644
index 0000000..3c82c46
--- /dev/null
+++ b/docs/contributing/documentation/index.md
@@ -0,0 +1,20 @@
+---
+title: Documentation
+description: Everything You Need to Know about Documenting Gardenlinux
+order: 3
+---
+
+# Documentation
+
+This section will tell you how to contribute documentation to Gardenlinux and
+its associated projects and what metrics we use to assess whether documentation
+is good.
+
+<SectionIndex />
+
+## References
+
+If you need to learn more about how to structure your documentation submission
+from a aggregated repository like `gardenlinux`, `builder` or
+`python-gardenlinux-lib`, please refer to the
+[documentation references](/reference/documentation/technical.md).
diff --git a/docs/contributing/documentation/writing_good_docs.md b/docs/contributing/documentation/writing_good_docs.md
new file mode 100644
index 0000000..ba58a3b
--- /dev/null
+++ b/docs/contributing/documentation/writing_good_docs.md
@@ -0,0 +1,185 @@
+---
+title: Documentation Quality Markers
+description: Writing Good Documentation
+order: 2
+---
+
+# Documentation Quality Markers
+
+Good documentation should follow concrete and actionable quality markers to be
+as helpful and professional as possible.
+
+These markers can roughly be split into required markers, that every
+documentation submission should have, and those which are context dependent and
+therefore optional.
+
+## Required Markers
+
+### Accuracy & Completeness
+
+It should go without saying that all documentation should be correct in an
+informational sense. Meaning all code and commands need to be tested and any
+tutorials & guides that are meant to lead a user through a process should be
+executed by the reviewer once to see if they do what they were written for.
+
+All code examples should:
+
+- Be tested and verified to work
+- Include expected output
+- Cover common error cases where applicable
+- Use realistic, representative examples
+
+All documents should cover all the aspects of their respective topics and not
+exclude edge cases even if they appear infrequent.
+
+Each document should clearly state:
+
+- Prerequisites (required knowledge, tools, or setup)
+- Context (when and why this information is relevant)
+- Next steps or related documentation
+
+### Readability
+
+One of the most important factors of good documentation is readability. This
+means that good documents should have a clear structure separated by concise
+headlines that serves both as a navigation aid and a red string through the
+topic.
+
+Another aspect of good readability is a well thought out **separation of
+thoughts**. Ideally, every thought should have its own paragraph. This goes hand
+in hand with keeping the sentence structure as short as possible and avoid
+overly complex or nested sentences if possible.
+
+Additional readability guidelines:
+
+- Use active voice over passive voice
+- Keep sentences focused (aim for 15-25 words)
+- Use progressive disclosure (introduce simple concepts before complex ones)
+- Break up long procedures into numbered steps
+
+### Style & Language
+
+All documentation should have a professional and inclusive tone. Gender-neutral
+language (like they/them or role based nouns like "maintainer", "developer" or
+"user") should be used. Language specific idioms common amongst native speakers
+should be avoided and project specific abbreviations should always link to their
+respective Glossary section.
+
+Hand in hand with the last point goes formulating documents with **consistent
+terminology**. To avoid confusion, especially in tutorials, certain terms like
+"install" and "set up" should not be used as synonyms, but instead have their
+own respective meanings.
+
+Documentation should go into appropriate detail for the intended audience (i.e.
+Users or Developers) and not omit any details or become vague when talking about
+specific topics.
+
+If a feature is not yet implemented or there are currently known bugs or Issues,
+a "Known Issues" section should be appended to the bottom of the document
+listing these issues and their corresponding GitHub issue if applicable.
+
+Include expected output or other steps which the reader can use to verify
+operation outcomes in any instructional guides.
+
+Use examples liberally across the documentation for any document that advises
+readers to action.
+
+### Usability & Accessibility
+
+Every person browsing documentation has different means and needs. Not only in
+the information they are looking for, but also how they access and process this
+documentation. Language barriers or disabilities may present barriers when
+attempting to look for something in documentation.
+
+There are a few things contributors can do to lower these barriers:
+
+- Use descriptive link texts instead of a simple "click here"
+- Images should have a descriptive alt text that explains what the image shows
+- Headings should have a proper hierarchy to ease browsing (don't skip heading
+  levels)
+- Code examples should have syntax highlighting
+- Navigation via keyboard must be possible across the site, the search bar
+  should ideally be accessible via key combination
+- In graphs and other visual media, **color alone must never be the only
+  indicator of differences or importance** - use icons, labels, or patterns as
+  well
+- All links should be verified as working (no dead links)
+- Links to external resources should specify version where applicable
+
+### Discoverability
+
+The best documentation is useless if no one can find it. All documents must be
+discoverable on all index pages or navigation bars and be linked in the
+appropriate context.
+
+Documents should:
+
+- Have clear, descriptive titles
+- Be placed in the appropriate section (Tutorial, How-to, Explanation,
+  Reference)
+- Be cross-referenced from related documentation
+- Include relevant keywords for search
+
+### Maintainability
+
+Documentation should be structured to minimize maintenance burden:
+
+- Follow the "single source of truth" principle; don't duplicate information
+  across multiple pages
+- Include version information where relevant
+- Clearly indicate ownership:
+  - For subproject documentation, the maintainers of that subproject
+    (identifiable via git blame) are responsible for updates
+  - For documentation hub content (like these guides), the Documentation Lead
+    owns maintenance if that role exists
+- Use includes or references for content that appears in multiple places
+
+## Conditional Markers
+
+### Version Compatibility
+
+Features that only apply to specific versions of Gardenlinux or supporting tools
+should be marked as such using markdown admonishments or any other suitable
+formatting to make them stand out.
+
+Breaking changes between versions should be indicated in an appropriately
+colored warning or info box at the top of the document.
+
+Version-specific content should include:
+
+- Minimum version required
+- Version where feature was introduced
+- Deprecation warnings if applicable
+
+## Checklist
+
+Use this checklist when reviewing or submitting documentation:
+
+### Core Markers
+
+- [ ] All code and commands are tested and working
+- [ ] Prerequisites are clearly stated
+- [ ] Expected output is shown for verification steps
+- [ ] Document has clear structure with descriptive headings
+- [ ] One main idea per paragraph
+- [ ] Sentences are concise and use active voice
+- [ ] Neutral and professional language throughout
+- [ ] Gender-neutral language used
+- [ ] Consistent terminology (no synonym confusion)
+- [ ] Project-specific abbreviations link to Glossary
+- [ ] All images have descriptive alt text
+- [ ] Links use descriptive text (not "click here")
+- [ ] Proper heading hierarchy maintained
+- [ ] Code examples have syntax highlighting
+- [ ] Color is not the only indicator in visual media
+- [ ] All links verified as working
+- [ ] Document is discoverable via navigation/index
+- [ ] Cross-referenced from related documentation
+- [ ] Clear ownership indicated
+
+### Conditional Markers
+
+- [ ] Version compatibility noted (if applicable)
+- [ ] Breaking changes highlighted (if applicable)
+- [ ] Known issues section included (if applicable)
+- [ ] External dependencies documented (if applicable)

From 77384b988ae38eb5df7d94a38566c84f65269357 Mon Sep 17 00:00:00 2001
From: Tiara Lena Hock <hock@b1-systems.de>
Date: Thu, 9 Apr 2026 08:17:28 +0200
Subject: [PATCH 4/8] Docs: Fix wording and add next steps sections

Signed-off-by: Tiara Lena Hock <hock@b1-systems.de>
---
 .../documentation/documentation_workflow.md   | 20 +++++++++++++------
 docs/contributing/documentation/index.md      |  4 ++--
 .../documentation/writing_good_docs.md        | 14 ++++++++++---
 3 files changed, 27 insertions(+), 11 deletions(-)

diff --git a/docs/contributing/documentation/documentation_workflow.md b/docs/contributing/documentation/documentation_workflow.md
index 136b15b..828e878 100644
--- a/docs/contributing/documentation/documentation_workflow.md
+++ b/docs/contributing/documentation/documentation_workflow.md
@@ -1,13 +1,13 @@
 ---
 title: Documentation Workflow
-description: How to Contribute Documentation to Gardenlinux
+description: How to Contribute Documentation to Garden Linux
 order: 1
 ---
 
-# Documenting Gardenlinux
+# Documenting Garden Linux
 
 This guide will provide you with a detailed overview over everything you need to
-know to support our efforts in documenting the Gardenlinux project.
+know to support our efforts in documenting the Garden Linux project.
 
 If you would like to know what markers we use to determine if submitted
 documentation is good, please check our guide about
@@ -27,7 +27,7 @@ to be documented accordingly.
 
 This includes, but is not limited to:
 
-- Usage of Gardenlinux and any supporting tool
+- Usage of Garden Linux and any supporting tool
 - Features and components of the project
 - Ways to contribute and where to find help
 - Information about where to submit security incidents
@@ -51,7 +51,7 @@ change is relevant for others.
 
 For example:
 
-1. A person introduces a new feature to Gardenlinux and opens a Pull Request
+1. A person introduces a new feature to Garden Linux and opens a Pull Request
 2. A maintainer reviews said feature and advises the contributor to write
    documentation for it
 3. Said documentation will be reviewed by the maintainer in question or the
@@ -94,7 +94,7 @@ Documentation ownership depends on the scope:
 
 ## How to Submit Documentation Changes
 
-To contribute documentation to Gardenlinux:
+To contribute documentation to Garden Linux:
 
 1. **Create a branch** named descriptively ideally with a `docs/` prefix
 2. **Make your changes** following the [quality markers](./writing_good_docs.md)
@@ -133,3 +133,11 @@ The review validates:
   text descriptions
 - **Maintainability**: Documentation follows single source of truth principle,
   ownership is clear, no unnecessary duplication
+
+## Next Steps
+
+Before you get started, you might want to check out the following docs:
+
+- [Documentation Quality Markers](./writing_good_docs.md)
+- [How to Documentation - Adding Repos to This Hub](/how-to/documentation/adding-repos.md)
+- [How to Documentation - Working With the Aggregator Locally](/how-to/documentation/working-locally.md)
diff --git a/docs/contributing/documentation/index.md b/docs/contributing/documentation/index.md
index 3c82c46..60ab286 100644
--- a/docs/contributing/documentation/index.md
+++ b/docs/contributing/documentation/index.md
@@ -1,12 +1,12 @@
 ---
 title: Documentation
-description: Everything You Need to Know about Documenting Gardenlinux
+description: Everything You Need to Know about Documenting Garde Linux
 order: 3
 ---
 
 # Documentation
 
-This section will tell you how to contribute documentation to Gardenlinux and
+This section will tell you how to contribute documentation to Garden Linux and
 its associated projects and what metrics we use to assess whether documentation
 is good.
 
diff --git a/docs/contributing/documentation/writing_good_docs.md b/docs/contributing/documentation/writing_good_docs.md
index ba58a3b..be35450 100644
--- a/docs/contributing/documentation/writing_good_docs.md
+++ b/docs/contributing/documentation/writing_good_docs.md
@@ -138,9 +138,9 @@ Documentation should be structured to minimize maintenance burden:
 
 ### Version Compatibility
 
-Features that only apply to specific versions of Gardenlinux or supporting tools
-should be marked as such using markdown admonishments or any other suitable
-formatting to make them stand out.
+Features that only apply to specific versions of Garden Linux or supporting
+tools should be marked as such using markdown admonishments or any other
+suitable formatting to make them stand out.
 
 Breaking changes between versions should be indicated in an appropriately
 colored warning or info box at the top of the document.
@@ -183,3 +183,11 @@ Use this checklist when reviewing or submitting documentation:
 - [ ] Breaking changes highlighted (if applicable)
 - [ ] Known issues section included (if applicable)
 - [ ] External dependencies documented (if applicable)
+
+## Next Steps
+
+Before you get started, you might want to check out the following docs:
+
+- [Documentation Workflow](./documentation_workflow.md)
+- [How to Documentation - Adding Repos to This Hub](/how-to/documentation/adding-repos.md)
+- [How to Documentation - Working With the Aggregator Locally](/how-to/documentation/working-locally.md)

From f8915259ca16fc92ab2c5460c142a30acd1deb18 Mon Sep 17 00:00:00 2001
From: Tiara Lena Hock <hock@b1-systems.de>
Date: Thu, 9 Apr 2026 13:40:19 +0200
Subject: [PATCH 5/8] Docs: Change Checklist to checkmarks

Signed-off-by: Tiara Lena Hock <hock@b1-systems.de>
---
 .../documentation/writing_good_docs.md        | 46 +++++++++----------
 1 file changed, 23 insertions(+), 23 deletions(-)

diff --git a/docs/contributing/documentation/writing_good_docs.md b/docs/contributing/documentation/writing_good_docs.md
index be35450..bf493c2 100644
--- a/docs/contributing/documentation/writing_good_docs.md
+++ b/docs/contributing/documentation/writing_good_docs.md
@@ -157,32 +157,32 @@ Use this checklist when reviewing or submitting documentation:
 
 ### Core Markers
 
-- [ ] All code and commands are tested and working
-- [ ] Prerequisites are clearly stated
-- [ ] Expected output is shown for verification steps
-- [ ] Document has clear structure with descriptive headings
-- [ ] One main idea per paragraph
-- [ ] Sentences are concise and use active voice
-- [ ] Neutral and professional language throughout
-- [ ] Gender-neutral language used
-- [ ] Consistent terminology (no synonym confusion)
-- [ ] Project-specific abbreviations link to Glossary
-- [ ] All images have descriptive alt text
-- [ ] Links use descriptive text (not "click here")
-- [ ] Proper heading hierarchy maintained
-- [ ] Code examples have syntax highlighting
-- [ ] Color is not the only indicator in visual media
-- [ ] All links verified as working
-- [ ] Document is discoverable via navigation/index
-- [ ] Cross-referenced from related documentation
-- [ ] Clear ownership indicated
+- ✅ All code and commands are tested and working
+- ✅ Prerequisites are clearly stated
+- ✅ Expected output is shown for verification steps
+- ✅ Document has clear structure with descriptive headings
+- ✅ One main idea per paragraph
+- ✅ Sentences are concise and use active voice
+- ✅ Neutral and professional language throughout
+- ✅ Gender-neutral language used
+- ✅ Consistent terminology (no synonym confusion)
+- ✅ Project-specific abbreviations link to Glossary
+- ✅ All images have descriptive alt text
+- ✅ Links use descriptive text (not "click here")
+- ✅ Proper heading hierarchy maintained
+- ✅ Code examples have syntax highlighting
+- ✅ Color is not the only indicator in visual media
+- ✅ All links verified as working
+- ✅ Document is discoverable via navigation/index
+- ✅ Cross-referenced from related documentation
+- ✅ Clear ownership indicated
 
 ### Conditional Markers
 
-- [ ] Version compatibility noted (if applicable)
-- [ ] Breaking changes highlighted (if applicable)
-- [ ] Known issues section included (if applicable)
-- [ ] External dependencies documented (if applicable)
+- ✅ Version compatibility noted (if applicable)
+- ✅ Breaking changes highlighted (if applicable)
+- ✅ Known issues section included (if applicable)
+- ✅ External dependencies documented (if applicable)
 
 ## Next Steps
 

From 6f8a096c32f96198676a02bcb776a9119d491723 Mon Sep 17 00:00:00 2001
From: Tiara Lena Hock <hock@b1-systems.de>
Date: Tue, 14 Apr 2026 10:11:12 +0200
Subject: [PATCH 6/8] Docs: Link references in contribution checklist

Signed-off-by: Tiara Lena Hock <hock@b1-systems.de>
---
 docs/contributing/documentation/documentation_workflow.md | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/docs/contributing/documentation/documentation_workflow.md b/docs/contributing/documentation/documentation_workflow.md
index 828e878..8e04320 100644
--- a/docs/contributing/documentation/documentation_workflow.md
+++ b/docs/contributing/documentation/documentation_workflow.md
@@ -98,9 +98,10 @@ To contribute documentation to Garden Linux:
 
 1. **Create a branch** named descriptively ideally with a `docs/` prefix
 2. **Make your changes** following the [quality markers](./writing_good_docs.md)
-3. **Add frontmatter** to your markdown files according to the
+3. **Add front-matter** to your markdown files according to the
    [technical reference](/reference/documentation/technical.md)
-4. **Test your changes** locally by running the documentation server
+4. **Test your changes** locally by running the documentation server Check the
+   [documentation testing guide](/reference/documentation/testing.md)
 5. **Open a Pull Request** with:
    - Clear description of what documentation was added/changed
    - Reference to any related code changes or issues

From 45f2cb38a774c09e00709f2b1327e405b4878209 Mon Sep 17 00:00:00 2001
From: Tiara Lena Hock <hock@b1-systems.de>
Date: Tue, 14 Apr 2026 13:59:03 +0200
Subject: [PATCH 7/8] Docs: Move all documentation for the documentation system
 to contributing

Signed-off-by: Tiara Lena Hock <hock@b1-systems.de>
---
 .../documentation/adding-repos.md             | 44 ++++++++-----
 .../documentation/aggregation-architecture.md | 62 ++++++++++++-------
 .../documentation/configuration.md            | 52 ++++++++++------
 .../documentation/documentation_workflow.md   | 18 ++++--
 docs/contributing/documentation/index.md      |  9 +--
 .../documentation/technical.md                | 59 +++++++++++-------
 .../documentation/testing.md                  | 26 +++++---
 .../documentation/working-locally.md          | 40 +++++++-----
 .../documentation/writing_good_docs.md        |  8 ++-
 9 files changed, 200 insertions(+), 118 deletions(-)
 rename docs/{how-to => contributing}/documentation/adding-repos.md (79%)
 rename docs/{explanation => contributing}/documentation/aggregation-architecture.md (83%)
 rename docs/{reference => contributing}/documentation/configuration.md (84%)
 rename docs/{reference => contributing}/documentation/technical.md (75%)
 rename docs/{reference => contributing}/documentation/testing.md (83%)
 rename docs/{how-to => contributing}/documentation/working-locally.md (68%)

diff --git a/docs/how-to/documentation/adding-repos.md b/docs/contributing/documentation/adding-repos.md
similarity index 79%
rename from docs/how-to/documentation/adding-repos.md
rename to docs/contributing/documentation/adding-repos.md
index 29ca354..adc3664 100644
--- a/docs/how-to/documentation/adding-repos.md
+++ b/docs/contributing/documentation/adding-repos.md
@@ -1,13 +1,15 @@
 ---
-title: "Adding Repositories to documentation aggregation"
+title: "Adding Repositories to Documentation Aggregation"
 description: "Guide for adding new repositories to the documentation aggregation system"
 ---
 
-# Adding Repositories to documentation aggregation
+# Adding Repositories to Documentation Aggregation
 
-This guide explains how to add a new repository to the documentation aggregation system.
+This guide explains how to add a new repository to the documentation aggregation
+system.
 
-> **Source Repository:** [gardenlinux/docs-ng](https://github.com/gardenlinux/docs-ng)
+> **Source Repository:**
+> [gardenlinux/docs-ng](https://github.com/gardenlinux/docs-ng)
 
 ## Prerequisites
 
@@ -41,9 +43,11 @@ Edit `repos-config.json` and add a new entry to the `repos` array:
 ### Optional Fields
 
 - **`commit`**: Lock to a specific commit hash for reproducibility
-- **`root_files`**: List of root-level files to copy (e.g., `["README.md", "CONTRIBUTING.md"]`)
+- **`root_files`**: List of root-level files to copy (e.g.,
+  `["README.md", "CONTRIBUTING.md"]`)
 - **`structure`**: Directory mapping strategy (see below)
-- **`media_directories`**: List of media directories to copy (e.g., `[".media", "_static", "assets"]`)
+- **`media_directories`**: List of media directories to copy (e.g.,
+  `[".media", "_static", "assets"]`)
 
 ## Step 2: Choose a Structure Strategy
 
@@ -78,7 +82,8 @@ Map source directories to Diataxis categories:
 
 ## Step 3: Configure Targeted Documentation
 
-To have files automatically placed into the main Diataxis structure, add `github_target_path` frontmatter to markdown files in the source repository:
+To have files automatically placed into the main Diataxis structure, add
+`github_target_path` front-matter to markdown files in the source repository:
 
 ```markdown
 ---
@@ -91,7 +96,8 @@ github_target_path: "docs/how-to/example-guide.md"
 Content here...
 ```
 
-Files with `github_target_path` will be copied to that exact location, not to `projects/<repo-name>/`.
+Files with `github_target_path` will be copied to that exact location, not to
+`projects/<repo-name>/`.
 
 ## Step 4: Test with Local Configuration
 
@@ -172,7 +178,8 @@ The system will:
 
 - Find all instances of these directories recursively
 - Copy nested media dirs (e.g., `tutorials/assets/`) to the same relative path
-- Copy root-level media dirs (e.g., `_static/`) to the common ancestor of targeted files
+- Copy root-level media dirs (e.g., `_static/`) to the common ancestor of
+  targeted files
 
 ### Root Files
 
@@ -185,7 +192,8 @@ Copy root-level files (like README.md or CONTRIBUTING.md):
 }
 ```
 
-These files can also have `github_target_path` frontmatter for targeted placement.
+These files can also have `github_target_path` front-matter for targeted
+placement.
 
 ### Special Files
 
@@ -233,7 +241,7 @@ Here's a complete configuration:
 
 - Verify `docs_path` points to the correct directory
 - Check that the repository has a `docs-ng` branch or adjust `ref`
-- Ensure `github_target_path` frontmatter is correct
+- Ensure `github_target_path` front-matter is correct
 
 ### Media Not Copied
 
@@ -246,9 +254,13 @@ Here's a complete configuration:
 - Check that relative links in source docs are correct
 - Review `src/aggregation/transformer.py` for link rewriting logic
 
-## See Also
+## Related Topics
 
-- [Adding Repositories](../../how-to/documentation/adding-repos.md) — How to add new repositories to the aggregation
-- [Technical Reference](../../reference/documentation/technical.md) — Source code and API documentation
-- [Configuration Reference](../../reference/documentation/configuration.md) — Complete configuration options
-- [Architecture Explanation](../../explanation/documentation/aggregation-architecture.md) — Deep dive into how the documentation aggregation system works
+- [Documentation Workflow](./documentation_workflow.md)
+- [Documentation Quality Markers](./writing_good_docs.md)
+- [Documentation Aggregator Architecture](./aggregation-architecture.md)
+- [How to Documentation - Adding Repos to Aggregate](./adding-repos.md)
+- [How to Documentation - Working With the Aggregator Locally](./working-locally.md)
+- [Documentation Aggregator Technical Reference](./technical.md)
+- [Documentation Aggregator Local Testing Guide](./testing.md)
+- [Working with the Documentation Hub on Your Machine](./working-locally.md)
diff --git a/docs/explanation/documentation/aggregation-architecture.md b/docs/contributing/documentation/aggregation-architecture.md
similarity index 83%
rename from docs/explanation/documentation/aggregation-architecture.md
rename to docs/contributing/documentation/aggregation-architecture.md
index 68ed350..50c5264 100644
--- a/docs/explanation/documentation/aggregation-architecture.md
+++ b/docs/contributing/documentation/aggregation-architecture.md
@@ -5,13 +5,16 @@ description: "Deep dive into how the documentation aggregation system works"
 
 # Documentation Aggregation Architecture
 
-Deep dive into the design and implementation of the documentation aggregation system.
+Deep dive into the design and implementation of the documentation aggregation
+system.
 
-> **Source Repository:** [gardenlinux/docs-ng](https://github.com/gardenlinux/docs-ng)
+> **Source Repository:**
+> [gardenlinux/docs-ng](https://github.com/gardenlinux/docs-ng)
 
 ## System Overview
 
-We use a documentation aggregation pipeline that combines content from multiple source repositories into a unified VitePress documentation site.
+We use a documentation aggregation pipeline that combines content from multiple
+source repositories into a unified VitePress documentation site.
 
 ```
 ┌─────────────────┐
@@ -33,7 +36,7 @@ We use a documentation aggregation pipeline that combines content from multiple
 ┌─────────────────┐
 │ Transform Stage │
 │ Rewrite links   │
-│ Fix frontmatter │
+│ Fix front-matter│
 └────────┬────────┘
          │
          ▼
@@ -58,8 +61,10 @@ We use a documentation aggregation pipeline that combines content from multiple
 
 **Mechanisms:**
 
-- **Git Sparse Checkout:** For remote repositories, uses sparse checkout to fetch only the `docs/` directory, minimizing clone size
-- **Local Copy:** For `file://` URLs, performs direct filesystem copy without git operations
+- **Git Sparse Checkout:** For remote repositories, uses sparse checkout to
+  fetch only the `docs/` directory, minimizing clone size
+- **Local Copy:** For `file://` URLs, performs direct filesystem copy without
+  git operations
 - **Commit Resolution:** Records the resolved commit hash for locking
 
 **Key Features:**
@@ -74,15 +79,16 @@ We use a documentation aggregation pipeline that combines content from multiple
 
 **Transformations:**
 
-1. **Link Rewriting:** Transform relative links to work across repository boundaries
+1. **Link Rewriting:** Transform relative links to work across repository
+   boundaries
 
    - Intra-repo links: Maintained relative to project mirror
    - Cross-repo links: Rewritten to absolute paths
    - External links: Preserved as-is
 
-2. **Frontmatter Handling:** Ensure all documents have proper frontmatter
+2. **Front-matter Handling:** Ensure all documents have proper front-matter
 
-   - Add missing frontmatter blocks
+   - Add missing front-matter blocks
    - Quote YAML values safely
    - Preserve existing metadata
 
@@ -94,8 +100,10 @@ We use a documentation aggregation pipeline that combines content from multiple
 
 **Operations:**
 
-1. **Targeted Documentation:** Copy files with `github_target_path` to specified locations
-2. **Directory Mapping:** Transform source directories according to `structure` config
+1. **Targeted Documentation:** Copy files with `github_target_path` to specified
+   locations
+2. **Directory Mapping:** Transform source directories according to `structure`
+   config
 3. **Media Copying:** Discover and copy media directories
 4. **Markdown Processing:** Apply transformations to all markdown files
 
@@ -109,7 +117,8 @@ We use a documentation aggregation pipeline that combines content from multiple
 
 ### Targeted Documentation
 
-Files with `github_target_path` frontmatter are copied directly to their specified location:
+Files with `github_target_path` front-matter are copied directly to their
+specified location:
 
 ```yaml
 ---
@@ -128,7 +137,8 @@ This allows fine-grained control over where content appears in the final site.
 
 ### Project Mirrors
 
-In addition to targeted docs, the entire `docs/` directory from each repo is mirrored under `docs/projects/<repo-name>/`:
+In addition to targeted docs, the entire `docs/` directory from each repo is
+mirrored under `docs/projects/<repo-name>/`:
 
 **Purpose:**
 
@@ -158,9 +168,9 @@ For reproducible builds, commits can be locked:
 
 ```json
 {
-  "name": "repo",
-  "ref": "main",
-  "commit": "abc123..."
+   "name": "repo",
+   "ref": "main",
+   "commit": "abc123..."
 }
 ```
 
@@ -186,7 +196,7 @@ This fetches the latest from `ref` and updates commit locks.
 - **Speed:** Faster than full clone, especially for large repos
 - **Minimal Disk Usage:** Reduces storage requirements
 
-### Why Frontmatter-Based Targeting?
+### Why Front-Matter-Based Targeting?
 
 - **Flexibility:** Authors control where their docs appear
 - **Decentralization:** No central mapping file to maintain
@@ -243,7 +253,7 @@ Temp Directory                 Docs Output
 ### Transform Stage
 
 - **Link rewriting:** O(n \* m) where n = files, m = avg file size
-- **Frontmatter:** O(n) single pass through files
+- **Front-matter:** O(n) single pass through files
 
 ### Structure Stage
 
@@ -267,7 +277,7 @@ Temp Directory                 Docs Output
 
 ### Transform Failures
 
-- Invalid frontmatter → Add default frontmatter, log warning
+- Invalid front-matter → Add default front-matter, log warning
 - Broken links → Log warning, preserve original link
 - Invalid markdown → Process as best-effort, log error
 
@@ -277,9 +287,13 @@ Temp Directory                 Docs Output
 - Conflicting file paths → Error with clear message
 - Media directory not found → Log warning, continue
 
-## See Also
+## Related Topics
 
-- [Adding Repositories](../../how-to/documentation/adding-repos.md) — How to add new repositories to the aggregation
-- [Technical Reference](../../reference/documentation/technical.md) — Source code and API documentation
-- [Configuration Reference](../../reference/documentation/configuration.md) — Complete configuration options
-- [Architecture Explanation](../../explanation/documentation/aggregation-architecture.md) — Deep dive into how the documentation aggregation system works
+- [Documentation Workflow](./documentation_workflow.md)
+- [Documentation Quality Markers](./writing_good_docs.md)
+- [Documentation Aggregator Architecture](./aggregation-architecture.md)
+- [How to Documentation - Adding Repos to Aggregate](./adding-repos.md)
+- [How to Documentation - Working With the Aggregator Locally](./working-locally.md)
+- [Documentation Aggregator Technical Reference](./technical.md)
+- [Documentation Aggregator Local Testing Guide](./testing.md)
+- [Working with the Documentation Hub on Your Machine](./working-locally.md)
diff --git a/docs/reference/documentation/configuration.md b/docs/contributing/documentation/configuration.md
similarity index 84%
rename from docs/reference/documentation/configuration.md
rename to docs/contributing/documentation/configuration.md
index 6d205bd..b66a60b 100644
--- a/docs/reference/documentation/configuration.md
+++ b/docs/contributing/documentation/configuration.md
@@ -7,19 +7,22 @@ description: "Complete reference for repos-config.json and repos-config.local.js
 
 Complete reference for configuring the documentation aggregation system.
 
-> **Source Repository:** [gardenlinux/docs-ng](https://github.com/gardenlinux/docs-ng)
+> **Source Repository:**
+> [gardenlinux/docs-ng](https://github.com/gardenlinux/docs-ng)
 
 ## Configuration Files
 
 ### `repos-config.json`
 
-Main configuration file for production aggregation. Uses git URLs and commit locks.
+Main configuration file for production aggregation. Uses git URLs and commit
+locks.
 
 **Location:** Project root
 
 ### `repos-config.local.json`
 
-Development configuration file for local testing. Uses `file://` URLs to avoid git operations.
+Development configuration file for local testing. Uses `file://` URLs to avoid
+git operations.
 
 **Location:** Project root
 
@@ -64,7 +67,8 @@ Development configuration file for local testing. Uses `file://` URLs to avoid g
 - **Examples:**
   - Git: `"https://github.com/gardenlinux/gardenlinux"`
   - Local: `"file://../gardenlinux"`
-- **Notes:** For local development, use `file://` URLs in `repos-config.local.json`
+- **Notes:** For local development, use `file://` URLs in
+  `repos-config.local.json`
 
 #### `docs_path`
 
@@ -103,7 +107,8 @@ Development configuration file for local testing. Uses `file://` URLs to avoid g
 - **Description:** Root-level files to copy (e.g., README.md, CONTRIBUTING.md)
 - **Example:** `["README.md", "CONTRIBUTING.md", "LICENSE"]`
 - **Default:** `[]` (no root files copied)
-- **Notes:** Files can have `github_target_path` frontmatter for targeted placement
+- **Notes:** Files can have `github_target_path` front-matter for targeted
+  placement
 
 #### `structure`
 
@@ -137,7 +142,8 @@ This maps source directories to Diataxis categories.
 - **Notes:**
   - Searched recursively in source repository
   - Nested media dirs (e.g., `tutorials/assets/`) copied to same relative path
-  - Root-level media dirs (e.g., `_static/`) copied to common ancestor of targeted files
+  - Root-level media dirs (e.g., `_static/`) copied to common ancestor of
+    targeted files
 
 #### `special_files`
 
@@ -257,7 +263,7 @@ Simplest configuration for a flat repository:
 
 ### With Targeted Documentation
 
-Repository using `github_target_path` frontmatter:
+Repository using `github_target_path` front-matter:
 
 ```json
 {
@@ -280,27 +286,37 @@ github_target_path: "docs/tutorials/my-tutorial.md"
 ---
 ```
 
-## Frontmatter Fields
+## Front-Matter Fields
 
 When using `github_target_path`, you can include additional metadata:
 
 - **`github_org`**: Organization name (e.g., `"gardenlinux"`)
 - **`github_repo`**: Repository name (e.g., `"docs-ng"`)
-- **`github_source_path`**: Original file path in source repo (e.g., `"docs/tutorial.md"`)
+- **`github_source_path`**: Original file path in source repo (e.g.,
+  `"docs/tutorial.md"`)
 
 These help create source links in the documentation.
 
 ### Page Display Fields
 
-- **`description`**: A short summary of the page. Used as the `<meta>` description by VitePress and shown in section index listings when `overviewDescriptions` is enabled on the parent page.
-- **`overviewDescriptions`**: Boolean controlling whether the `<SectionIndex />` component displays child page descriptions. Defaults to `true`. Set to `false` on an index page to hide descriptions for its listing.
-- **`order`**: Numeric value for controlling sort order in the sidebar and section listings. Lower values appear first.
-- **`migration_status`**: Status for content migration (e.g., `"new"`, `"adapt"`, `"aggregate"`).
+- **`description`**: A short summary of the page. Used as the `<meta>`
+  description by VitePress and shown in section index listings when
+  `overviewDescriptions` is enabled on the parent page.
+- **`overviewDescriptions`**: Boolean controlling whether the `<SectionIndex />`
+  component displays child page descriptions. Defaults to `true`. Set to `false`
+  on an index page to hide descriptions for its listing.
+- **`order`**: Numeric value for controlling sort order in the sidebar and
+  section listings. Lower values appear first.
+- **`migration_status`**: Status for content migration (e.g., `"new"`,
+  `"adapt"`, `"aggregate"`).
 
 ## See Also
 
-- [Working with the Documentation System Locally](../../how-to/documentation/working-locally.md)
-- [Testing Reference](./testing.md) — Test suite documentation
-- [Adding Repositories](../../how-to/documentation/adding-repos.md) — How to add new repos
-- [Technical Reference](./technical.md) — Source code documentation
-- [Architecture](../../explanation/documentation/aggregation-architecture.md) — System design
+- [Documentation Workflow](./documentation_workflow.md)
+- [Documentation Quality Markers](./writing_good_docs.md)
+- [Documentation Aggregator Architecture](./aggregation-architecture.md)
+- [How to Documentation - Adding Repos to Aggregate](./adding-repos.md)
+- [How to Documentation - Working With the Aggregator Locally](./working-locally.md)
+- [Documentation Aggregator Technical Reference](./technical.md)
+- [Documentation Aggregator Local Testing Guide](./testing.md)
+- [Working with the Documentation Hub on Your Machine](./working-locally.md)
diff --git a/docs/contributing/documentation/documentation_workflow.md b/docs/contributing/documentation/documentation_workflow.md
index 8e04320..4a6e245 100644
--- a/docs/contributing/documentation/documentation_workflow.md
+++ b/docs/contributing/documentation/documentation_workflow.md
@@ -28,6 +28,7 @@ to be documented accordingly.
 This includes, but is not limited to:
 
 - Usage of Garden Linux and any supporting tool
+- Processes used to develop or maintain Garden Linux or any supporting tool
 - Features and components of the project
 - Ways to contribute and where to find help
 - Information about where to submit security incidents
@@ -99,9 +100,9 @@ To contribute documentation to Garden Linux:
 1. **Create a branch** named descriptively ideally with a `docs/` prefix
 2. **Make your changes** following the [quality markers](./writing_good_docs.md)
 3. **Add front-matter** to your markdown files according to the
-   [technical reference](/reference/documentation/technical.md)
+   [technical reference](./technical.md)
 4. **Test your changes** locally by running the documentation server Check the
-   [documentation testing guide](/reference/documentation/testing.md)
+   [documentation testing guide](./testing.md)
 5. **Open a Pull Request** with:
    - Clear description of what documentation was added/changed
    - Reference to any related code changes or issues
@@ -135,10 +136,17 @@ The review validates:
 - **Maintainability**: Documentation follows single source of truth principle,
   ownership is clear, no unnecessary duplication
 
-## Next Steps
+## Related Topics
 
 Before you get started, you might want to check out the following docs:
 
 - [Documentation Quality Markers](./writing_good_docs.md)
-- [How to Documentation - Adding Repos to This Hub](/how-to/documentation/adding-repos.md)
-- [How to Documentation - Working With the Aggregator Locally](/how-to/documentation/working-locally.md)
+- [Documentation Aggregator Architecture](./aggregation-architecture.md)
+- [How to Documentation - Adding Repos to Aggregate](./adding-repos.md)
+- [How to Documentation - Working With the Aggregator Locally](./working-locally.md)
+- [Documentation Aggregator Technical Reference](./technical.md)
+- [Documentation Aggregator Local Testing Guide](./testing.md)
+- [Working with the Documentation Hub on Your Machine](./working-locally.md)
+
+> **Source Repository:**
+> [gardenlinux/docs-ng](https://github.com/gardenlinux/docs-ng)
diff --git a/docs/contributing/documentation/index.md b/docs/contributing/documentation/index.md
index 60ab286..259d685 100644
--- a/docs/contributing/documentation/index.md
+++ b/docs/contributing/documentation/index.md
@@ -1,7 +1,7 @@
 ---
 title: Documentation
 description: Everything You Need to Know about Documenting Garde Linux
-order: 3
+order: 0
 ---
 
 # Documentation
@@ -11,10 +11,3 @@ its associated projects and what metrics we use to assess whether documentation
 is good.
 
 <SectionIndex />
-
-## References
-
-If you need to learn more about how to structure your documentation submission
-from a aggregated repository like `gardenlinux`, `builder` or
-`python-gardenlinux-lib`, please refer to the
-[documentation references](/reference/documentation/technical.md).
diff --git a/docs/reference/documentation/technical.md b/docs/contributing/documentation/technical.md
similarity index 75%
rename from docs/reference/documentation/technical.md
rename to docs/contributing/documentation/technical.md
index b4c78e1..ac830a3 100644
--- a/docs/reference/documentation/technical.md
+++ b/docs/contributing/documentation/technical.md
@@ -7,7 +7,10 @@ description: "Source code documentation for the documentation aggregation system
 
 Source code documentation for the documentation aggregation system.
 
-> **Source Repository:** [gardenlinux/docs-ng](https://github.com/gardenlinux/docs-ng) > **Source File:** [src/README.md](https://github.com/gardenlinux/docs-ng/blob/main/src/README.md)
+> **Source Repository:**
+> [gardenlinux/docs-ng](https://github.com/gardenlinux/docs-ng) > **Source
+> File:**
+> [src/README.md](https://github.com/gardenlinux/docs-ng/blob/main/src/README.md)
 
 ## Source Code Structure
 
@@ -48,33 +51,40 @@ Repository fetching:
 
 Methods:
 
-- **`__init__(project_root, update_locks=False)`** — Initialize with optional commit lock updating
+- **`__init__(project_root, update_locks=False)`** — Initialize with optional
+  commit lock updating
 - **`fetch()`** — Fetch repository and return result with commit hash
 - **`_fetch_remote()`** — Git sparse checkout from remote repository
 - **`_fetch_local()`** — Filesystem copy from local repository
 - **`_copy_docs()`** — Static method to copy docs directory
-- **`_copy_root_files()`** — Static method to copy root-level files (e.g., CONTRIBUTING.md)
+- **`_copy_root_files()`** — Static method to copy root-level files (e.g.,
+  CONTRIBUTING.md)
 
 ### `aggregation/transformer.py`
 
 Content transformation:
 
 - **`rewrite_links()`** — Fix markdown links for cross-repository references
-- **`quote_yaml_value()`** — YAML safety for frontmatter values
-- **`ensure_frontmatter()`** — Add or fix frontmatter in markdown files
-- **`parse_frontmatter()`** — Extract metadata from markdown frontmatter
+- **`quote_yaml_value()`** — YAML safety for front-matter values
+- **`ensure_frontmatter()`** — Add or fix front-matter in markdown files
+- **`parse_frontmatter()`** — Extract metadata from markdown front-matter
 - **`fix_broken_project_links()`** — Validate and fix links to project mirrors
 
 ### `aggregation/structure.py`
 
 Directory operations:
 
-- **`transform_directory_structure()`** — Restructure docs based on config mapping
-- **`copy_targeted_docs(source_dir, docs_dir, repo_name, media_dirs=None, root_files=None)`** — Copy files with `github_target_path` frontmatter to specified locations
-  - Handles nested media dirs (e.g., `tutorials/assets/`) by copying to same relative path
-  - Handles root-level media dirs (e.g., `_static/`) by copying to common ancestor of targeted files
+- **`transform_directory_structure()`** — Restructure docs based on config
+  mapping
+- **`copy_targeted_docs(source_dir, docs_dir, repo_name, media_dirs=None, root_files=None)`**
+  — Copy files with `github_target_path` front-matter to specified locations
+  - Handles nested media dirs (e.g., `tutorials/assets/`) by copying to same
+    relative path
+  - Handles root-level media dirs (e.g., `_static/`) by copying to common
+    ancestor of targeted files
   - Supports scanning root_files for targeted placement
-- **`process_markdown_file()`** — Transform single markdown file (links, frontmatter)
+- **`process_markdown_file()`** — Transform single markdown file (links,
+  front-matter)
 - **`process_all_markdown()`** — Batch process all markdown files in directory
 
 ### `aggregate.py`
@@ -105,7 +115,8 @@ process_all_markdown(target_dir, repo_name)
 
 ### Targeted Documentation
 
-Files with `github_target_path` in their frontmatter are automatically placed at that exact path:
+Files with `github_target_path` in their front-matter are automatically placed
+at that exact path:
 
 ```yaml
 ---
@@ -113,11 +124,13 @@ github_target_path: "docs/tutorials/example.md"
 ---
 ```
 
-The `copy_targeted_docs()` function scans all markdown files and copies those with this frontmatter to their specified locations.
+The `copy_targeted_docs()` function scans all markdown files and copies those
+with this front-matter to their specified locations.
 
 ### Link Rewriting
 
-The `rewrite_links()` function transforms markdown links to work in the aggregated site:
+The `rewrite_links()` function transforms markdown links to work in the
+aggregated site:
 
 - Relative links within the same repo are maintained
 - Cross-repository links are rewritten to point to the correct locations
@@ -129,7 +142,8 @@ Media directories specified in `media_directories` configuration are:
 
 1. Discovered recursively in the source repository
 2. Copied alongside their associated documentation
-3. Placed according to whether they're nested (same relative path) or root-level (common ancestor)
+3. Placed according to whether they're nested (same relative path) or root-level
+   (common ancestor)
 
 ### Commit Locking
 
@@ -168,13 +182,16 @@ To add a new structure mapping type:
 Key architectural decisions are documented in the source repository:
 
 - Sparse git checkout for efficiency
-- Frontmatter-based targeting for flexibility
+- Front-matter-based targeting for flexibility
 - Separate fetch/transform/structure stages for modularity
 
 ## See Also
 
-- [Working with the Documentation System Locally](../../how-to/documentation/working-locally.md)
-- [Testing Reference](./testing.md) — Test suite documentation
-- [Adding Repositories](../../how-to/documentation/adding-repos.md) — How to add new repos
-- [Configuration Reference](./configuration.md) — Complete configuration field reference
-- [Architecture Explanation](../../explanation/documentation/aggregation-architecture.md) — How the system works
+- [Documentation Workflow](./documentation_workflow.md)
+- [Documentation Quality Markers](./writing_good_docs.md)
+- [Documentation Aggregator Architecture](./aggregation-architecture.md)
+- [How to Documentation - Adding Repos to Aggregate](./adding-repos.md)
+- [How to Documentation - Working With the Aggregator Locally](./working-locally.md)
+- [Documentation Aggregator Technical Reference](./technical.md)
+- [Documentation Aggregator Local Testing Guide](./testing.md)
+- [Working with the Documentation Hub on Your Machine](./working-locally.md)
diff --git a/docs/reference/documentation/testing.md b/docs/contributing/documentation/testing.md
similarity index 83%
rename from docs/reference/documentation/testing.md
rename to docs/contributing/documentation/testing.md
index 8253d16..c04d5ec 100644
--- a/docs/reference/documentation/testing.md
+++ b/docs/contributing/documentation/testing.md
@@ -7,7 +7,10 @@ description: "Test suite for documentation - unit tests, integration tests, and
 
 Test suite documentation for the documentation aggregation system.
 
-> **Source Repository:** [gardenlinux/docs-ng](https://github.com/gardenlinux/docs-ng) > **Source File:** [tests/README.md](https://github.com/gardenlinux/docs-ng/blob/main/tests/README.md)
+> **Source Repository:**
+> [gardenlinux/docs-ng](https://github.com/gardenlinux/docs-ng) > **Source
+> File:**
+> [tests/README.md](https://github.com/gardenlinux/docs-ng/blob/main/tests/README.md)
 
 ## Test Structure
 
@@ -66,7 +69,8 @@ Test pure functions with no I/O side effects:
 
 - **Link rewriting** (`rewrite_links`) — Transform markdown links
 - **YAML quoting** (`quote_yaml_value`) — Safely quote YAML values
-- **Frontmatter handling** (`ensure_frontmatter`, `parse_frontmatter`) — Parse and manipulate frontmatter
+- **Front-matter handling** (`ensure_frontmatter`, `parse_frontmatter`) — Parse
+  and manipulate front-matter
 - **Config loading/saving** — Parse and write configuration files
 - **Model validation** — Data class validation and serialization
 
@@ -88,7 +92,7 @@ Integration tests are slower and require temporary directories.
 Located in `tests/fixtures/`, these provide:
 
 - Sample markdown files
-- Example frontmatter configurations
+- Example front-matter configurations
 - Mock repository structures
 - Configuration file examples
 
@@ -212,7 +216,8 @@ export PYTHONPATH="${PYTHONPATH}:$(pwd)"
 
 ### Fixture Not Found
 
-Check that `conftest.py` is in the correct location and properly defines fixtures.
+Check that `conftest.py` is in the correct location and properly defines
+fixtures.
 
 ### Integration Tests Failing
 
@@ -224,8 +229,11 @@ Integration tests may fail if:
 
 ## See Also
 
-- [Working with the Documentation System Locally](../../how-to/documentation/working-locally.md)
-- [Adding Repositories](../../how-to/documentation/adding-repos.md) — How to add new repositories to the aggregation
-- [Technical Reference](../../reference/documentation/technical.md) — Source code and API documentation
-- [Configuration Reference](../../reference/documentation/configuration.md) — Complete configuration options
-- [Architecture Explanation](../../explanation/documentation/aggregation-architecture.md) — Deep dive into how the documentation aggregation system works
+- [Documentation Workflow](./documentation_workflow.md)
+- [Documentation Quality Markers](./writing_good_docs.md)
+- [Documentation Aggregator Architecture](./aggregation-architecture.md)
+- [How to Documentation - Adding Repos to Aggregate](./adding-repos.md)
+- [How to Documentation - Working With the Aggregator Locally](./working-locally.md)
+- [Documentation Aggregator Technical Reference](./technical.md)
+- [Documentation Aggregator Local Testing Guide](./testing.md)
+- [Working with the Documentation Hub on Your Machine](./working-locally.md)
diff --git a/docs/how-to/documentation/working-locally.md b/docs/contributing/documentation/working-locally.md
similarity index 68%
rename from docs/how-to/documentation/working-locally.md
rename to docs/contributing/documentation/working-locally.md
index 26870e3..6045e52 100644
--- a/docs/how-to/documentation/working-locally.md
+++ b/docs/contributing/documentation/working-locally.md
@@ -5,13 +5,18 @@ description: "Learn how to contribute to Garden Linux documentation — working
 
 # Contributing to the Garden Linux Documentation
 
-Garden Linux documentation is published at **https://gardenlinux-docs.netlify.app/** and combines content from multiple repositories into a unified documentation site.
+Garden Linux documentation is published at
+**https://gardenlinux-docs.netlify.app/** and combines content from multiple
+repositories into a unified documentation site.
 
-> **Source Repository:** [gardenlinux/docs-ng](https://github.com/gardenlinux/docs-ng)
+> **Source Repository:**
+> [gardenlinux/docs-ng](https://github.com/gardenlinux/docs-ng)
 
 ## Working with the Documentation System Locally
 
-For more substantial changes — like adding new pages, restructuring content, or working on the aggregation system itself — you'll want to set up the documentation system locally.
+For more substantial changes — like adding new pages, restructuring content, or
+working on the aggregation system itself — you'll want to set up the
+documentation system locally.
 
 ### Prerequisites
 
@@ -32,7 +37,8 @@ cd docs-ng
 pnpm install
 ```
 
-This installs VitePress and other Node.js dependencies needed to build the documentation site.
+This installs VitePress and other Node.js dependencies needed to build the
+documentation site.
 
 ### Step 3: Aggregate Documentation
 
@@ -44,7 +50,8 @@ Aggregate from locked commits in `repos-config.json`:
 make aggregate
 ```
 
-This fetches documentation from the configured repositories at their locked commit hashes.
+This fetches documentation from the configured repositories at their locked
+commit hashes.
 
 #### From Local Repositories (Development)
 
@@ -123,9 +130,9 @@ docs/
 
 ## Next Steps
 
-- Learn how to [add new repositories](../../how-to/documentation/adding-repos)
-- Understand the [architecture](../../explanation/architecture)
-- Review the [configuration reference](../../reference/documentation/configuration)
+- Learn how to [add new repositories](adding-repos.md)
+- Understand the [architecture](./aggregation-architecture.md)
+- Review the [configuration reference](./configuration.md)
 
 ## Troubleshooting
 
@@ -150,13 +157,16 @@ python3 --version  # Should be 3.x
 
 ### Verify Configuration
 
-Check that `repos-config.json` or `repos-config.local.json` is properly configured. See the [configuration reference](../../reference/documentation/configuration) for details.
+Check that `repos-config.json` or `repos-config.local.json` is properly
+configured. See the [configuration reference](./configuration.md) for details.
 
 ## See Also
 
-- [Quick Edits](../../tutorials/documentation.md)
-- [Working with the Documentation System Locally](../../how-to/documentation/working-locally.md)
-- [Testing Reference](../../reference/documentation/testing.md) — Test suite documentation
-- [Adding Repositories](../../how-to/documentation/adding-repos.md) — How to add new repos
-- [Technical Reference](../../reference/documentation/technical.md) — Source code documentation
-- [Architecture](../../explanation/documentation/aggregation-architecture.md) — System design
+- [Documentation Workflow](./documentation_workflow.md)
+- [Documentation Quality Markers](./writing_good_docs.md)
+- [Documentation Aggregator Architecture](./aggregation-architecture.md)
+- [How to Documentation - Adding Repos to Aggregate](./adding-repos.md)
+- [How to Documentation - Working With the Aggregator Locally](./working-locally.md)
+- [Documentation Aggregator Technical Reference](./technical.md)
+- [Documentation Aggregator Local Testing Guide](./testing.md)
+- [Working with the Documentation Hub on Your Machine](./working-locally.md)
diff --git a/docs/contributing/documentation/writing_good_docs.md b/docs/contributing/documentation/writing_good_docs.md
index bf493c2..a5cc03a 100644
--- a/docs/contributing/documentation/writing_good_docs.md
+++ b/docs/contributing/documentation/writing_good_docs.md
@@ -189,5 +189,9 @@ Use this checklist when reviewing or submitting documentation:
 Before you get started, you might want to check out the following docs:
 
 - [Documentation Workflow](./documentation_workflow.md)
-- [How to Documentation - Adding Repos to This Hub](/how-to/documentation/adding-repos.md)
-- [How to Documentation - Working With the Aggregator Locally](/how-to/documentation/working-locally.md)
+- [Documentation Aggregator Architecture](./aggregation-architecture.md)
+- [How to Documentation - Adding Repos to Aggregate](./adding-repos.md)
+- [How to Documentation - Working With the Aggregator Locally](./working-locally.md)
+- [Documentation Aggregator Technical Reference](./technical.md)
+- [Documentation Aggregator Local Testing Guide](./testing.md)
+- [Working with the Documentation Hub on Your Machine](./working-locally.md)

From 94c60f7e609853756b8cc35a85717170ae35075d Mon Sep 17 00:00:00 2001
From: Tiara Lena Hock <hock@b1-systems.de>
Date: Tue, 14 Apr 2026 13:59:23 +0200
Subject: [PATCH 8/8] Docs: Delete redundant documentation tutorial

Signed-off-by: Tiara Lena Hock <hock@b1-systems.de>
---
 docs/tutorials/documentation.md | 28 ----------------------------
 1 file changed, 28 deletions(-)
 delete mode 100644 docs/tutorials/documentation.md

diff --git a/docs/tutorials/documentation.md b/docs/tutorials/documentation.md
deleted file mode 100644
index e61021e..0000000
--- a/docs/tutorials/documentation.md
+++ /dev/null
@@ -1,28 +0,0 @@
----
-title: "Contributing to the Garden Linux Documentation"
-description: "Learn how to contribute to Garden Linux documentation — quick edits"
----
-
-# Contributing to the Garden Linux Documentation
-
-Garden Linux documentation is published at **https://gardenlinux-docs.netlify.app/** and combines content from multiple repositories into a unified documentation site.
-
-> **Source Repository:** [gardenlinux/docs-ng](https://github.com/gardenlinux/docs-ng)
-
-## Quick Edits — The Easy Way
-
-The easiest way to improve the documentation is directly from the published site:
-
-1. **Navigate to any page** on https://gardenlinux-docs.netlify.app/
-2. **Scroll to the bottom** of the page
-3. **Click "Edit this page on GitHub"** — this opens the source file in the correct repository
-4. **Make your edits** using GitHub's web editor
-5. **Submit a pull request** — the changes will be automatically aggregated into the documentation site
-
-## See Also
-
-- [Working with the Documentation System Locally](../how-to/documentation/working-locally.md)
-- [Testing Reference](../reference/documentation/testing.md) — Test suite documentation
-- [Adding Repositories](../how-to/documentation/adding-repos.md) — How to add new repos
-- [Technical Reference](../reference/documentation/technical.md) — Source code documentation
-- [Architecture](../explanation/documentation/aggregation-architecture.md) — System design