3.2 KiB
| title | order |
|---|---|
| Writing Documentation | 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
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 btw.
Go ahead and clone the repository:
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/ 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
---
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/.