From 6bf25e55db86565db8ee560ecc2f2aaa07abd32c Mon Sep 17 00:00:00 2001 From: twisti-dev <76837088+twisti-dev@users.noreply.github.com> Date: Tue, 2 Jun 2026 20:19:13 +0200 Subject: [PATCH 1/3] =?UTF-8?q?=F0=9F=93=9D=20docs:=20update=20guidelines?= =?UTF-8?q?=20for=20agents=20and=20add=20styleguide=20for=20documentation?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - revise agent guidelines to clarify documentation standards - introduce styleguide for consistent writing and formatting - emphasize direct address and avoidance of gendered language --- AGENTS.md | 304 +++++++++++++++++++++++++++++++++++++++----------- STYLEGUIDE.md | 284 ++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 521 insertions(+), 67 deletions(-) create mode 100644 STYLEGUIDE.md diff --git a/AGENTS.md b/AGENTS.md index 2e32fb19..6f4e4950 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,72 +1,242 @@ -# Richtlinien für Codex Agents +# Richtlinien für Agents -Diese Datei erläutert, wie Änderungen in diesem Repository vorgenommen werden sollen. Das Repository verwendet [Writerside](https://www.jetbrains.com/help/writerside/) von JetBrains für die Dokumentation. Writerside basiert auf Markdown, bietet jedoch zusätzliche Funktionen wie Snippets, Variablen und spezielle Tags. +Diese Datei beschreibt, wie KI-Agents und andere automatisierte Werkzeuge Änderungen in diesem Repository durchführen sollen. -## Allgemeine Regeln -- Schreibe alle neuen Inhalte auf Deutsch. -- Achte auf eine freundliche, leicht verständliche Ausdrucksweise. -- Bestehende Dateien dürfen nicht ohne Grund gelöscht werden. -- Nutze Pull Requests mit aussagekräftigen Beschreibungen. +Das Repository verwendet Writerside von JetBrains für die Dokumentation. Writerside basiert auf Markdown und erweitert es um XML-Tags, Includes, Variablen und spezielle Attribute. + +Der verbindliche Sprach- und Formatierungsstandard steht in [`STYLEGUIDE.md`](STYLEGUIDE.md). + +## Grundregeln + +- Schreibe alle neuen und überarbeiteten Inhalte auf Deutsch. +- Befolge den Styleguide in [`STYLEGUIDE.md`](STYLEGUIDE.md). +- Verwende grundsätzlich die direkte Ansprache mit „du“. +- Verwende keine gegenderte Sprache wie `Spielende`, `jede*r`, `Nutzer:innen` oder ähnliche Formen. +- Erhalte alle vorhandenen Informationen vollständig. +- Lösche keine bestehenden Inhalte ohne klaren Grund. +- Ändere keine Regeln, Warnungen oder Hinweise inhaltlich. +- Verwende eine freundliche, klare und leicht verständliche Sprache. +- Erstelle Pull Requests mit aussagekräftiger Beschreibung. + +## Wichtige Arbeitsweise + +Bei jeder Änderung gilt: + +1. Lies die betroffene Datei vollständig genug, um den Kontext zu verstehen. +2. Ändere nur das, was zur Aufgabe gehört. +3. Erhalte Struktur, Reihenfolge und Bedeutung der Inhalte. +4. Prüfe nach der Änderung, ob keine Information verloren gegangen ist. +5. Prüfe Links, IDs, Variablen und Writerside-Markup besonders sorgfältig. + +Wenn eine Formulierung unklar ist, formuliere konservativ um oder lasse sie unverändert. + +## Sprachstil + +Die Dokumentation spricht Leser grundsätzlich mit „du“ an. + +Bevorzugte Formulierungen: + +- „du kannst …“ +- „du erhältst …“ +- „du findest …“ +- „wenn du …“ +- „beachte …“ + +Vermeide unnötige Wechsel zwischen: + +- „du“ +- „ihr“ +- „man“ +- „die Spieler“ + +„Ihr“ ist nur erlaubt, wenn eindeutig eine Gruppe gemeinsam angesprochen wird. + +## Gender-Regeln + +Verwende keine gegenderte Sprache mit Sonderzeichen oder künstlichen Ersatzformen. + +Nicht verwenden: + +- `Spielende` +- `Nutzende` +- `Teilnehmende` +- `jede*r` +- `Nutzer:innen` +- `Spieler/innen` +- `SpielerInnen` + +Verwende stattdessen das generische Maskulinum oder eine natürliche neutrale Formulierung. + +Beispiele: + +- `Spieler` +- `Nutzer` +- `Teilnehmer` +- `jeder` +- `die Community` +- `alle` +- `das Team` + +Neutrale Formulierungen sind erlaubt, wenn sie natürlich und unauffällig wirken. + +## Einheitliche Terminologie + +Verwende die Schreibweisen aus dem Styleguide. + +Besonders wichtig: + +- `Community-Server` +- `Survival-Server` +- `Event-Server` +- `SMP-Server` +- `Serverregeln` +- `Shopsystem` +- `Skillsystem` +- `Skillmenü` +- `Befehl` +- `Modifikation` +- `Minecraft-Version` +- `TNT-Duper` + +Eigennamen, Itemnamen, Plugin-Namen, UI-Bezeichnungen, Variablen und Befehle dürfen nicht unnötig verändert werden. + +## Typografie + +Achte auf korrekte deutsche Typografie. + +Beispiele: + +- `z. B.` +- `d. h.` +- `u. a.` +- `10 %` +- `550 Spielstunden` + +Verwende geschützte Leerzeichen, wo Begriffe nicht getrennt werden sollen. + +Verändere keine technischen Variablen wie: + +- `%main_currency%` +- `%dc_link%` +- `%required_game_version%` ## Writerside-spezifische Hinweise - - Writerside unterstützt Standard-Markdown sowie erweiterte Tags und eine XML-basierte Semantik. - - Wiederverwendbare Inhalte definierst du mit `...`. - - Über `` bindest du Snippets in andere Seiten ein. - - Variablen aus `Writerside/v.list` kannst du über `%varname%` nutzen. - - Hinweise und Warnungen werden mit `{style="note"}` bzw. `{style="warning"}` erzeugt. - - Registerkarten lassen sich mit `` und `` aufbauen. - - Definitionen verwendest du mit `` und ``. - - Neue Dokumentationsdateien legst du unter `Writerside/topics/` an. Die Struktur sollte zu den vorhandenen Unterordnern passen. - - Bilder kommen in `Writerside/images/`, Videos in `Writerside/videos/`. - - Achte darauf, IDs für Überschriften zu vergeben (`## Titel {id="..."}`), damit Links stabil bleiben. - - Bevor du Inhalte veröffentlichst, führe das Writerside-Build-Skript aus (falls vorhanden), um sicherzustellen, dass die Dokumentation fehlerfrei gerendert wird. - -### Kurzübersicht zum Writerside-Markup -Writerside kombiniert CommonMark mit zahlreichen XML‑Tags. Ein paar der wichtigsten Funktionen aus der Dokumentation sind: - -- **Absätze und Text**: Einfache Absätze brauchen keine besonderen Tags. Für Textblöcke kannst du `

` verwenden und über `{id="..."}` eigene IDs setzen. -- **Strukturelle Blöcke**: Verwende `` für längere Themenblöcke oder `` mit `` für Schritt‑an‑Schritt-Anleitungen. Inhaltslisten baust du mit `` oder ``, Tabellen mit ``, ``, `
`. -- **Ein- und ausklappbare Abschnitte**: `` bzw. `` ermöglichen Akkordeon-ähnliche Inhalte. -- **Links und Querverweise**: `[Linktext](url)` funktioniert wie gewohnt. Für interne Verweise gibt es ``. -- **Medieneinbindung**: Bilder bindest du über `![Alt-Text](path)` oder `Text` ein, Videos mit `