---
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
    uv run 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/).