add some documentation structure

docs/guides/writing-documentation.md

@@ -0,0 +1,99 @@
+---
+title: Writing Documentation
+order: 1
+---
+
+!!! success "Goal"
+
+    How to add a new article to this documentation or modify an existing one so that it is understandable, discoverable and fosters understanding.
+
+## 1. Understand the Structure
+
+You need to understand how we write documentation and which rules and structures you should follow when you are adding things (don't worry, it's not too much).
+For this purpose, please read the accompanying document [Documentation Structure](../concepts-and-configurations/documentation-structure.md)
+
+## 2. Clone the Repository
+
+On the top right of this page is a GitHub icon which leads you to the repository containing this documentation.
+It's [git.hamburg.ccc.de/ccchh/ansible-infra.git](https://git.hamburg.ccc.de/ccchh/ansible-infra.git) btw.
+
+Go ahead and clone the repository:
+
+```shell
+git clone ssh://forgejo@git.hamburg.ccc.de/CCCHH/ansible-infra.git
+```
+
+## 3. Add/Edit your Markdown File
+
+Once you have cloned the repository, you can just edit a file in the [`docs/`](https://git.hamburg.ccc.de/CCCHH/ansible-infra/src/branch/main/docs) under the correct
+
+!!! info
+
+    Our documentation software will automatically discover any new files and assets.
+    You don't need to touch any configuration or index files.
+
+!!! note
+
+    You can preview your changes by running the following commands:
+    ```shell
+    uv venv
+    uv pip install -r docs_requirements.txt
+    mkdocs serve
+    ```
+
+When adding new content, you can use one of the templates below to get started:
+
+/// details | Template for *Guides*
+```markdown
+---
+title: My new Guide
+---
+
+!!! success "Goal"
+
+    Add s small summary describing the end-goal this guide helps a reader achieve
+
+## 1. Step One
+
+## 2. Step Two
+
+## ...
+
+## Closing Up
+
+This section is optional but if there's any way for the reader to verify their goal has been achieved, you should mention it here.
+```
+///
+
+/// details | Template for *Concepts and Configurations*
+!!! danger "TODO"
+///
+
+## 4. Open a Pull-Request
+
+After writing your changes locally, push them to the git repository and open a Pull-Request.
+
+<a target="_blank" href="https://git.hamburg.ccc.de/CCCHH/ansible-infra/compare/main...main">
+  <button style="cursor: pointer;">Open Pull-Request</button>
+</a>
+
+After the PR is opened, our CI/CD will automatically build the new documentation version and comment a link to your deployed changes on your PR.
+If everything looks good, request a review from one of the existing team members.
+
+## 5. Review a Pull-Request
+
+!!! warning
+
+    This section is meant to be done by a PR reviewer
+
+When reviewing documentation Pull-Requests, make sure of the following criteria:
+
+- All changed content should be correct and up-to-date.
+- If new content is added, it should either be clearly a guide or belong to *Concepts and Configurations*. If both content types are mixed, they should be split up.
+- Ensure all added or edited hyperlinks are working and pointing to the correct targets.
+- Look at the deployed staging version and make sure there is no rendering fuckery going on.
+
+## Closing Up
+
+After everything is merged and done your changes will be automatically deployed over at [https://infra-docs.hamburg.ccc.de/](https://infra-docs.hamburg.ccc.de/).
+