99 lines
3.2 KiB
Markdown
99 lines
3.2 KiB
Markdown
---
|
|
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/).
|
|
|