From 5ca311d24006c7798b43a5d329cabf3f46495a5d Mon Sep 17 00:00:00 2001 From: lilly Date: Sat, 23 May 2026 19:37:49 +0200 Subject: [PATCH] add some documentation structure --- .../certificate-management.md | 0 .../documentation-structure.md | 16 +++ docs/concepts-and-configurations/index.md | 10 ++ .../keycloak_auth_concept.md | 0 .../managed-resources.md | 0 .../networking_in_chaosknoten.md | 0 .../networking_in_z9.md | 0 .../concepts-and-configurations/who-we-are.md | 17 ++++ docs/guides/add_z9_static_ip.md | 0 docs/guides/index.md | 13 +++ docs/guides/offboarding.md | 0 docs/guides/onboarding.md | 3 + docs/guides/writing-documentation.md | 99 +++++++++++++++++++ docs/index.md | 10 +- mkdocs.yml | 2 + 15 files changed, 168 insertions(+), 2 deletions(-) create mode 100644 docs/concepts-and-configurations/certificate-management.md create mode 100644 docs/concepts-and-configurations/documentation-structure.md create mode 100644 docs/concepts-and-configurations/index.md create mode 100644 docs/concepts-and-configurations/keycloak_auth_concept.md create mode 100644 docs/concepts-and-configurations/managed-resources.md create mode 100644 docs/concepts-and-configurations/networking_in_chaosknoten.md create mode 100644 docs/concepts-and-configurations/networking_in_z9.md create mode 100644 docs/concepts-and-configurations/who-we-are.md create mode 100644 docs/guides/add_z9_static_ip.md create mode 100644 docs/guides/index.md create mode 100644 docs/guides/offboarding.md create mode 100644 docs/guides/onboarding.md create mode 100644 docs/guides/writing-documentation.md diff --git a/docs/concepts-and-configurations/certificate-management.md b/docs/concepts-and-configurations/certificate-management.md new file mode 100644 index 0000000..e69de29 diff --git a/docs/concepts-and-configurations/documentation-structure.md b/docs/concepts-and-configurations/documentation-structure.md new file mode 100644 index 0000000..0ca89d3 --- /dev/null +++ b/docs/concepts-and-configurations/documentation-structure.md @@ -0,0 +1,16 @@ +--- +title: Documentation Structure +order: 1 +summary: >- + How our documentation is organized and what we do to balance ease of writing and understanding. +--- + +!!! info "ToDo" + + This section needs updating + +- 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 + diff --git a/docs/concepts-and-configurations/index.md b/docs/concepts-and-configurations/index.md new file mode 100644 index 0000000..80125f6 --- /dev/null +++ b/docs/concepts-and-configurations/index.md @@ -0,0 +1,10 @@ +--- +title: Concepts and Configurations +order: 0 +sidebar_title: Start +summary: >- + Concepts and configurations is a selection of how we organize and manage our infrastructure. You can find here how processes are planned, how services are expected to integrate with each other and how they are configured. + +--- + + diff --git a/docs/concepts-and-configurations/keycloak_auth_concept.md b/docs/concepts-and-configurations/keycloak_auth_concept.md new file mode 100644 index 0000000..e69de29 diff --git a/docs/concepts-and-configurations/managed-resources.md b/docs/concepts-and-configurations/managed-resources.md new file mode 100644 index 0000000..e69de29 diff --git a/docs/concepts-and-configurations/networking_in_chaosknoten.md b/docs/concepts-and-configurations/networking_in_chaosknoten.md new file mode 100644 index 0000000..e69de29 diff --git a/docs/concepts-and-configurations/networking_in_z9.md b/docs/concepts-and-configurations/networking_in_z9.md new file mode 100644 index 0000000..e69de29 diff --git a/docs/concepts-and-configurations/who-we-are.md b/docs/concepts-and-configurations/who-we-are.md new file mode 100644 index 0000000..04fc70e --- /dev/null +++ b/docs/concepts-and-configurations/who-we-are.md @@ -0,0 +1,17 @@ +--- +title: Who We Are and What We Do +--- + +We are the infrastructure team of the [Chaos Computer Club Hansestadt Hamburg](https://hambugr.ccc.de). + We operate all the infrastructure related to that club in a fun, sustainable and cooperative way. +We are always open for new ideas and discussions and you can reach us at [infra@hamburg.ccc.de](mailto:infra@hamburg.ccc.de) or directly in the hackerspace. + +In doing so we operate on common values of **trust**, **fun**, helping each other learn, and of course the [Hacker Ethics](https://www.ccc.de/en/hackerethics). + +Topics that interest us and which we engage in: + +- Networking in our local club (See [Networking in Z9](./networking_in_z9.md)) +- Operating our own bare metal servers in Club and our local data center (See [Managed Resources](./managed-resources.md)) +- Providing services for our members and groups (See [Managed Resources](./managed-resources.md)) +- Hacking on (self hosted) Smart-Home services and automation for our space (See [Club Automation](./club-automation.md)) + diff --git a/docs/guides/add_z9_static_ip.md b/docs/guides/add_z9_static_ip.md new file mode 100644 index 0000000..e69de29 diff --git a/docs/guides/index.md b/docs/guides/index.md new file mode 100644 index 0000000..4f1312d --- /dev/null +++ b/docs/guides/index.md @@ -0,0 +1,13 @@ +--- +title: Guides +order: 0 +sidebar_title: Start +summary: >- + Guides are your one-stop-shop for reaching a certain goal. + You want to achieve something? The relevant guide will give you step-by-step instructions on how to do it. +--- + +For a complete list, see the sidebar on the left but the important guides everyone should know are the following: + +- [Writing Documentation](./writing-documentation.md) + diff --git a/docs/guides/offboarding.md b/docs/guides/offboarding.md new file mode 100644 index 0000000..e69de29 diff --git a/docs/guides/onboarding.md b/docs/guides/onboarding.md new file mode 100644 index 0000000..d948286 --- /dev/null +++ b/docs/guides/onboarding.md @@ -0,0 +1,3 @@ +# Onboarding + +TODO diff --git a/docs/guides/writing-documentation.md b/docs/guides/writing-documentation.md new file mode 100644 index 0000000..fd2681f --- /dev/null +++ b/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. + + + + + +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/). + diff --git a/docs/index.md b/docs/index.md index 9c1e48e..f6a6e9c 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,5 +1,11 @@ # CCCHH Infrastructure Documentation -Home for CCCHH infrastructure documentation. +Welcome, this is the home of the CCCHH infrastructure documentation. +For an introduction, see the selection of important articles below: + +- [Who We Are and What We Do](./concepts-and-configurations/who-we-are.md) +- [Onboarding](./guides/onboarding.md) +- [Guides](./guides/index.md) for goal oriented step-by-step instructions. +- [Concepts and Configurations](./concepts-and-configurations/index.md) for a explanations about how things work and why we things a certain way. +- [Writing Documentation](./guides/writing-documentation.md) -- **Guides**: Documentation on how to achieve various things. diff --git a/mkdocs.yml b/mkdocs.yml index f5c2358..0ae452d 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -2,11 +2,13 @@ site_name: CCCHH Infrastructure Documentation site_url: https://infra-docs.hamburg.ccc.de repo_url: https://git.hamburg.ccc.de/CCCHH/ansible-infra copyright: MIT + markdown_extensions: - smarty - admonition - attr_list - codehilite + - pymdownx.blocks.details - pymdownx.superfences: css_class: codehilite