Nicht nur Code bestimmt die Softwarequalität, sondern auch die Art, wie Softwareentwicklerinnen und -entwickler ihn dokumentieren und präsentieren. In einer Zeit, in der viele Entwicklerteams vollständig remote arbeiten und die Codebase weiter kontinuierlich wächst, ist die konsistente und automatisierte Qualitätskontrolle eine Notwendigkeit.

Während meiner Arbeit an einem node-basierten Dokumentationsstack mit dem Static-Site-Generator Astro und Starlight, einem darauf aufbauenden Framework speziell für Dokumentationswebsites, bin ich auf die Herausforderung gestoßen, nicht nur sauberen Code, sondern auch hochwertige Prosa zu produzieren. Prosa kommt aus dem Lateinischen und bedeutet „geradeheraus reden“ – also ohne Schnörkel normal sprechen.

Im Rahmen einer Dokumentation bezeichnet Prosa den gesamten ausformulierten Textinhalt der technischen Dokumentation – alle Erklärungen, Anleitungen, Beschreibungen und Kommentare. Ziel ist es, dass Stil-Konsistenz, Grammatik, Wortwahl, Lesbarkeit und die Einhaltung von Dokumentationsrichtlinien sichergestellt sind und die technische Dokumentation nicht nur funktional korrekt, sondern auch verständlich, einheitlich und professionell geschrieben ist.

Die Lösung: Ein mehrstufiges Linting-System, das Code-Qualität, Formatierung und Prosa-Linting für englischsprachige Dokumentation geschickt miteinander verbindet und sich durch Git Pre-Commit Hooks sowie CI/CD-Pipelines automatisieren lässt. Prosa Linting für deutsche Texte ist nicht nativ integriert, lässt sich aber durch eigene Regeln integrieren. Hierbei kann die KI bei der Erstellung der Regeln gute Dienste tun. Eine gute Hilfestellung bietet hier auch der webbasierte Regelgenerator valegen.

Test-Setup: Astrogon als Grundlage für das Linting-System

Bevor es an die detaillierte Umsetzung des dreistufigen Linting-Konzepts geht, ist eine praktische Arbeitsumgebung einzurichten. Als grundlegendes Code- und Dokumentations-Beispiel dient Astrogon – ein vielseitiges Astro-Theme, das sich ideal für die Demonstration des Linting-Systems eignet. Astrogon ist ein schnell anpassbares, Mehrzweck-Website-Template, das auf Astro JS, Tailwind CSS und React basiert. So bildet es eine solide Grundlage für verschiedene Website-Typen – von Blogs über Dokumentationsseiten bis hin zu Portfolio-Websites.

Astrogon eignet sich deshalb als Demo-Basis, weil es:

1. Verschiedene Dateitypen enthält: .astro, .tsx, .js, .md, .mdx, .css
2. Realistische Komplexität bietet: ein echtes Projekt mit authentischen Herausforderungen
3. Einen modernen Stack verwendet: aktuelle Technologien, die typisch für moderne Webprojekte sind
4. Gut strukturiert ist: klare Ordnerstruktur für effektives Linting
5. Content-fokussiert arbeitet: viel Text-Content für Prosa-Linting

Durch einen Fork des originalen Astrogon Repository, den man lokal klont, lässt sich das Projekt einfach aufsetzen.

# Create a fork (via GitHub.com)

#  Clone repository
git clone 
cd my-linting-project

# Install dependencies
npm install

# Fix existing vulnerabilities
npm audit fix

# Start development server
npm run dev

Nach der Installation steht eine vollständig funktionsfähige Website mit folgender Struktur parat:

my-linting-project/
├── docs/ # Documentation
├── public/ # Static public viewable resources
├── src/
│ ├── assets/ # Pictures, icons,...
│ ├── components/ # reusable components
│ ├── content/ # Markdown/MDX content collections
│ ├── lib/ # Utility functions
│ ├── pages/ # Astro-pages (Routing)
│ ├── styles/ # CSS/SCSS files
│ ├── types/ # TypeScript type-definitions
│ ├── content.config.ts # Content Collections configuration
│ └── env.d.ts # Environment variables types
├── .editorconfig # Editor-configuration
├── .prettierrc # Preconfigured prettier
├── .markdownlint.json # Preconfigured markdownlot
├── astro.config.mjs # Astro configuration
├── package.json # Dependencies and scripts
├── tailwind.config.js # Tailwind CSS configuration
├── tsconfig.json # TypeScript Configuration
└── wrangler.jsonc # Cloudflare workers configuration

Integration der Linter in den Stack

Modernes Linting geht weit über die reine Syntaxprüfung hinaus und umfasst drei komplementäre Dimensionen der Qualitätskontrolle: Code-Qualität für die Logik, Formatierung für die Konsistenz und Prosa-Linting für die menschliche Lesbarkeit. Für diese drei Aspekte kommen verschiedene Linter zum Einsatz: ESLint für die Code-Qualität, Prettier für die Formatierung und Vale für das Prosa-Linting.

Code-Qualität mit ESLint: ESLint bildet das Fundament des Linting-Stacks. Es analysiert TypeScript-, JavaScript- und Astro-Dateien auf potenzielle Fehler, Style-Inkonsistenzen und Best-Practice-Verletzungen. Die Installation leitet der folgende Befehl ein:

npm install -D eslint @typescript-eslint/eslint-plugin @typescript-eslint/parser astro-eslint-parser eslint-plugin-astro

Im nächsten Schritt folgt das Anlegen der Datei .eslintrc.js, die die Konfiguration für die verschiedenen Dateitypen definiert. Dies gelingt am einfachsten über den offiziellen Konfigurations-Wizard von ESLint:

npm init @eslint/config@latest

module.exports = {
  extends: [
    "eslint:recommended",
    "plugin:@typescript-eslint/recommended",
  ],
  parser: "@typescript-eslint/parser",
  plugins: ["@typescript-eslint"],
  parserOptions: {
    ecmaVersion: "latest",
    sourceType: "module",
  },
  env: {
    node: true,
    browser: true,
    es2022: true,
  },
  rules: {
    "@typescript-eslint/no-unused-vars": ["error", { "argsIgnorePattern": "^_" }],
    "@typescript-eslint/no-explicit-any": "warn",
    "@typescript-eslint/no-empty-interface": "off",
  },
  overrides: [
    {
      files: ["*.astro"],
      extends: ["plugin:astro/recommended"],
      parser: "astro-eslint-parser",
      parserOptions: {
        parser: "@typescript-eslint/parser",
        extraFileExtensions: [".astro"],
      },
    },
  ],
};

Anschließend sind die aufrufenden npm-Skripte in der Datei package.json zu hinterlegen.

{
  "scripts": {
    "lint": "eslint ./src --ext .js,.ts,.jsx,.tsx,.astro --fix",
    "lint:check": "eslint ./src --ext .js,.ts,.jsx,.tsx,.astro"
  }
}

Der Befehl npm run lint korrigiert dann automatisch behebbare Probleme, während npm run lint:check nur überprüft, ohne Änderungen vorzunehmen, und die Ergebnisse im Terminal ausgibt.

Code-Formatierung mit Prettier: Prettier sorgt für einheitliche Code-Formatierung und nimmt Entwicklern die Diskussion über Code-Style ab. Besonders in Astro-Projekten mit gemischten Dateitypen ist eine konsistente Formatierung essenziell. Prettier lässt sich mit folgendem Befehl installieren:

npm install -D prettier prettier-plugin-astro prettier-plugin-tailwindcss

Die Konfiguration von .prettierrc\ im Root-Verzeichnis des Repository berücksichtigt die spezifischen Anforderungen von Astro-Projekten:

{
  "plugins": ["prettier-plugin-astro", "prettier-plugin-tailwindcss"],
  "semi": true,
  "singleQuote": false,
  "tabWidth": 2,
  "trailingComma": "es5",
  "printWidth": 80,
  "useTabs": false,
  "bracketSpacing": true,
  "bracketSameLine": false,
  "arrowParens": "always",
  "endOfLine": "lf",
  "overrides": [
    {
      "files": ["*.astro"],
      "options": {
        "parser": "astro"
      }
    },
    {
      "files": ["*.md", "*.mdx"],
      "options": {
        "printWidth": 100,
        "proseWrap": "always"
      }
    }
  ]
}

Sind die Abhängigkeiten installiert und die Konfiguration angelegt, werden die entsprechenden npm-Skripte in der Datei package.json eingefügt:

{
  "scripts": {
      ...
      ...
    "format": "prettier --write ./src --log-level silent",
    "format:check": "prettier --check ./src --log-level silent"
  }
}

Der Befehl npm run format korrigiert anschließend automatisch behebbare Probleme, während npm run format:check nur überprüft, ohne Änderungen vorzunehmen, und die Ergebnisse im Terminal ausgibt.

Prosa-Linting mit Vale: Vale ist ein Open-Source-Tool für das Prosa-Linting, das wie ein Code-Linter funktioniert, aber Fließtext verarbeitet. Es prüft Texte auf stilistische Fehler, wiederkehrende Muster und Verstöße gegen vordefinierte oder eigene Stilrichtlinien. Es funktioniert mit Markdown, HTML, AsciiDoc oder reStructuredText und analysiert diese Formate anhand konfigurierter Regeln. Die Style-Guides, anhand derer Vale überprüft, können frei gewählt, angepasst oder erweitert werden – beispielsweise nach Vorbildern von Google, Microsoft oder eigenen Anforderungen.

Typische Regeln erkennen etwa unnötige Passiv-Konstruktionen, zu viele Wiederholungen, fehlende Oxford-Kommas – also das Komma vor der Konjunktion in einer Aufzählung, das helfen soll, Missverständnisse zu vermeiden – oder „Weak Words“ wie „viele“ oder „manchmal“. Die Ergebnisse zeigt Vale direkt im Editor, in der Kommandozeile oder als Teil automatisierter CI-Prozesse.

Vale erfordert eine plattformspezifische Installation sowie den Download der Style-Guides und LibreOffice-kompatibler Hunspell-Wörterbücher (.dic/.aff-Dateien) für die Rechtschreibprüfung in anderen Sprachen als Englisch. Ja, die Kombination von Prosa-Linting-Style-Guides (wie Vale, Google oder Microsoft Style Guides) mit einem deutschen Wörterbuch ist durchaus sinnvoll und funktioniert einwandfrei – Vale nutzt Hunspell-Dictionaries unabhängig voneinander für Rechtschreibung und Stilregeln. Rechtschreibprüfung prüft Wörter auf Korrektheit, während Prosa-Linting Stil, Lesbarkeit und Konventionen überwacht; beide ergänzen sich nahtlos in einem Workflow. Für das beispielhafte Repository habe ich entsprechende Linux/macOS– und Windows-Skripte angelegt, die das Setup erledigen. Getestet ist aktuell nur das Bash-Skript, das PowerShell-Skript wurde via KI automatisiert auf Basis des Bash-Skripts erstellt.

Abweichend von der standardmäßigen Vorgehensweise, bei der Probleme mit dem in Vale integrierten Installer vale sync auftraten, laden die Skripte die git-Repositories für die Styleguides manuell herunter und löschen alle git-spezifischen Inhalte.

# Linux/macOS
chmod +x .vale/install-vale.sh
./.vale/install-vale.sh

# Windows
powershell -ExecutionPolicy Bypass -File .vale/install-vale.ps1

Nach Ausführen der Skripte entsteht folgendes Verzeichnis im Root-Verzeichnis des Repositories:

my-linting-project/
├── .vale/
  ├── dictionaries
  │    ├── de_DE.aff
  │    ├── de_DE.dic
  ├── styles
       ├── Base
       │    ├── accept.txt
	   │    ├── reject.txt
       │    ├── Microsoft/
       │    ├── write-good/ 
  ├── install-vale.ps1
  ├── install-vale.sh
  └── vale

Zu beachten ist dabei noch, alle dynamisch generierten Inhalte in die .gitignore-Datei aufzunehmen.

# Vale binary (install with npm run install-vale)
.vale/dictionaries
.vale/styles/Microsoft
.vale/styles/write-good
.vale/vale
.vale/vale.exe

Vale-Styleguides auswählen und installieren

Das Installationsskript lädt nicht nur Vale herunter, sondern auch die benötigten Styleguides. Auf der Vale-Website sind, neben einigen weiteren spezifischen, vier wesentliche Style-Guides referenziert:

Google

• Starker Fokus auf technische Konsistenz und Präzision für Entwickler.
• Große Ausnahmeliste für Akronyme und Begriffe aus APIs.
• Substitutionslisten mit Google-typischer Terminologie.
• Stil: direkt, technisch, an Entwickler gerichtet, prägnant, präzise.
• Quelle Git, Quelle Style-Guide

Microsoft

• Sehr starke Gewichtung auf Inklusivität und Barrierefreiheit.
• Klare Satzlängen- und Limits für Wörter.
• Hunderte produkt- und communityspezifische Begriffe.
• Stil: freundlich, inklusiv, leserorientiert, markengerecht, barrierefrei.
• Quelle Git, Quelle Style-Guide

Red Hat

• Strikte Regeln zu „Open Source“-neutraler Sprache und Kollaboration.
• Erlaubt keinen Produkt-Bias, eigene Accessibility- und Bias-Listen.
• Regeln für CLI-Beispiele, Dateipfade und produktneutrale Formulierungen.
• Bevorzugt kollaborativen Duktus und Community-Perspektive.
• Stil: offen, kollaborativ, communitygetrieben, produktneutral, inklusiv.
• Quelle Git, Quelle Style-Guide

Write-good

• Fokussiert sich rein auf sprachliche Klarheit und verbessert Lesbarkeit und Stil, ohne produkt- oder technikspezifische Prüfkriterien.
• In modernen Dokumentations-Workflows eignen sich Write-Good-Regeln ergänzend, um die sprachliche Qualität unabhängig von der Plattform zu verbessern.
• Write-Good Vale Style-Guide

Im Folgenden kommt der „Microsoft Style Guide“ zum Einsatz – erweitert um die Style-Guides „write-good“, „MDX“ und „Vale Core“. Diese sind wie folgt charakterisiert:

Microsoft Style Guide: Unternehmensstandards für technische Dokumentation

write-good: allgemeine Regeln für klares Schreiben

Vale Core: grundlegende Prosa-Regeln

MDX: Prüfung der Sprache innerhalb von JSX Tags

Beim Einsatz unterschiedlicher Style-Guides in Kombination lässt sich in manchen Situationen schwer identifizieren, warum welche Regel benötigt wird. Ein Beispiel macht dies klarer. Gegeben ist folgende MDX-Datei:

---
title: "Using Feature Y"
author: "Adesso"
---

# Feature Y Benefits

You will be able to use this feature very effectively. It was developed by adeso and their team.


  DO NOT use this feature if your environment isn't set correctly.


Step 1: Initializing the data source
Step 2 Call the performOperation() function
Step 3: Confirm the output's accuracy

> Note: The process can be slow. It is important that you wait patiently.

For details, check our doc [documentation](htp://example.com/feature-y).

Die Ergebnisse des Lintings fasst die folgende Tabelle zusammen:

Fehler	Welcher Regelsatz	Erklärungen & Korrektur
Autor „Adesso“ und „adeso“ inkonsistent geschrieben	Custom Regel	Korrigiert in „adesso“
Großschreibung in JSX-Komponente ``	MDX-Regelsatz	Meldet falsche Großschreibung oder unbekannte JSX-Tags, erwartet `` o.Ä.
Markdown-Liste ohne korrekte Aufzählungszeichen	MDX-Regelsatz	Fehlt das `-` oder die Nummerierung bei Liste (z.B. `Step 2` ist kein Listenelement)
Unsichere URL im Link (htp statt http)	Microsoft Regelsatz	Erkennt ungültige URLs, fordert Korrektur auf gültiges Schema (`
Übermäßiger Gebrauch von Floskeln (z.B. „very effectively“, „It is important that“)	Write-Good	Empfiehlt prägnantere Ausdrucksweise („effectively“, „Wait patiently.“)
Use of first-person pronouns („You will be able…“, „you wait patiently“) in nicht passender Art	Microsoft Regelsatz	Warnt bei unpassender Verwendung von Personalpronomen, schlägt Sparse-Usage vor
Passiver Sprachgebrauch („was developed“)	Write-Good & Microsoft	Empfiehlt aktive Formulierung, z.B. „adesso developed this feature.“

Die korrigierte MDX-Datei sieht nach der Regelprüfung dann wie folgt aus:

---
title: "Using Feature Y"
author: "adesso"
---

# Feature Y Benefits

You can use this feature effectively, adesso and their team developed it.


  Do not use this feature if your environment is not set correctly.


- Step 1: Initialize the data source
- Step 2: Call the performOperation() function
- Step 3: Confirm the output's accuracy

> Note: The process can be slow. Please wait patiently.

For details, check our [documentation](

Mithin ergeben sich folgende Einschränkungen:

• Die Vale-Style-Guides sind nur für englischen Text optimiert, eine Anpassung an Deutsch oder andere Sprachen scheint bisher nicht vorgesehen zu sein.
• Die Style-Guides basieren auf klassischen Regular Expressions. Wer KI-basierte Ansätze erwartet, wird enttäuscht.
• Speziell in größeren Projekten empfiehlt es sich einen eigenen Style-Guide aufzubauen. Die Konfiguration von Vale erfordert eine kontinuierliche Anpassung an die Bedürfnisse des Projekts.

Konfigurieren und Anpassen von Vale (.vale.ini)

Die Vale-Konfigurationsdatei gibt an, in welchen Verzeichnissen und mit welchen Style-Vorgaben das Tool den Text überprüfen soll. Für das Beispiel sei angenommen, dass sich der englische Content in den Unterverzeichnissen des Ordners /src/content befindet.

# Vale configuration file
# See: 
Packages = MDX

StylesPath = .vale/styles
# Add dictionary path for German dictionaries
DictionaryPath = .vale/dictionaries

MinAlertLevel = error

# File type associations - English content (excluding German docs)
[src/content/**]{.md,.mdx}

# Enable/disable specific styles for English content
BasedOnStyles = Vale, write-good, Microsoft

# Enable rules
Vale.Terms = YES  # Disables term-based checks. Example: Avoid using "jargon".
Vale.Spelling = YES  # Disables spelling checks. Example: "recieve" instead of "receive".
Vale.Vocab = YES  # Disables vocabulary checks. Example: Using "utilize" instead of "use".
Vale.Repetition = YES  # Disables repetition checks. Example: "very very good".
Vale.Wordiness = YES  # Disables wordiness checks. Example: "in order to" instead of "to".

# Write-good rules (English-specific)
write-good.Weasel = YES  # Disables detection of weasel words. Example: "some people say".
write-good.TooWordy = YES  # Disables detection of overly wordy phrases. Example: "due to the fact that".
write-good.So = YES  # Disables detection of sentences starting with "so". Example: "So, we decided to...".
write-good.ThereIs = YES  # Disables detection of "there is/are" constructions. Example: "There is a need for...".
write-good.Passive = YES  # Disables detection of passive voice. Example: "The ball was thrown by John".
write-good.Adverbs = YES  # Disables detection of adverbs. Example: "He ran quickly".
write-good.Cliches = YES  # Disables detection of cliches. Example: "Think outside the box".
write-good.E-Prime = YES  # Disables detection of E-Prime violations. Example: "He is a teacher".
write-good.Illusions = YES  # Disables detection of ambiguous phrases. Example: "The results were significant".

# Microsoft style rules (English-specific)
Microsoft.Gender = YES  # Ensures gender-neutral language is used. Example: Use "they" instead of "he/she".
Microsoft.PassiveVoice = YES  # Flags sentences written in passive voice. Example: "The report was written by Sarah".
Microsoft.Cliches = YES  # Detects overused phrases and cliches. Example: "At the end of the day".
Microsoft.Jargon = YES  # Highlights technical jargon that may confuse readers. Example: "Leverage synergies".
Microsoft.Complexity = YES  # Identifies sentences that are overly complex or difficult to read. Example: "The implementation of the solution was carried out in a manner that ensured...".
Microsoft.Redundancy = YES  # Flags redundant phrases or words. Example: "Free gift".
Microsoft.Spelling = YES  # Checks for spelling errors based on Microsoft's style guide. Example: "color" vs. "colour".
Microsoft.Spacing = YES  # Disables because of D2 diagrams - Allows ignoring spacing-related issues. Example: "word  word".
Microsoft.Contracting = YES  # Allows ignoring contracting-related issues. Example: "isn't" vs. "is not".
Microsoft.Quotes = YES  # Allows ignoring quotes-related issues. Example: "'single quotes' vs. "double quotes".
Microsoft.Contractions = YES  # Allows ignoring contractions-related issues. Example: "can't" vs. "cannot".
Microsoft.Foreign = YES  # Allows ignoring foreign phrases and words. Example: "et cetera".
Microsoft.Plurals = YES  # Allows ignoring pluralization-related issues. Example: "criterias" vs. "criteria".
Microsoft.Auto = YES  # Disables automatic suggestions for corrections. Example: "autocorrect".
Microsoft.AMPM = YES  # Allows ignoring AM/PM formatting issues. Example: "2 PM" vs. "14:00".
Microsoft.DateOrder = YES  # Allows ignoring date order-related issues. Example: "MM/DD/YYYY" vs. "DD/MM/YYYY".
Microsoft.Dashes = YES  # Allows ignoring dash-related issues. Example: "em-dash" vs. "en-dash".
Microsoft.DateFormat = YES  # Allows ignoring date format-related issues. Example: "2025-10-01" vs. "01/10/2025".
Microsoft.Units = YES  # Allows ignoring unit-related issues. Example: "5kg" vs. "5 kg".
Microsoft.Avoid = YES  # Allows ignoring "avoid" suggestions. Example: "Avoid using passive voice".
Microsoft.Negative = YES  # Allows ignoring negative phrasing suggestions. Example: "Not bad" vs. "Good".

Nun sind noch die richtigen Cross-Platform npm-Skripte für Vale bereitzustellen, um den Linter zu installieren und aufzurufen.

{
  "scripts": {
	  ...
	  ...
    "postinstall": "npm run install-vale",
	"install-vale": "node -e \"const cmd = process.platform === 'win32' ? 'powershell -ExecutionPolicy Bypass -File .vale/install-vale.ps1' : 'bash .vale/install-vale.sh'; require('child_process').exec(cmd, (err, stdout, stderr) => { if (err) { console.error(stderr); process.exit(1); } console.log(stdout); })\"",
    "prose": "node -e \"const vale = process.platform === 'win32' ? './.vale/vale.exe' : './.vale/vale'; const { exec } = require('child_process'); exec(vale + ' --config=.vale.ini src/content', (err, stdout, stderr) => { console.log(stdout); if (stderr) console.error(stderr); if (err) process.exit(1); });\""
  }
}

• postinstall: Wird automatisch aufgerufen, wenn npm install ausgeführt wird
• install-vale: Ruft je nach Plattform die richtigen Installationsscripte auf
• prose: Ruft das Linting auf und gibt Fehler in der Kategorie „error“, „warning“ und „information“ aus

Ausnahmen für Sonderfälle sind eigens zu definieren, etwa für Situationen, in denen Vale eine Regel bewusst ignorieren soll. Beispielsweise würde die Regel write-good.So für den Satz „So the experiment failed because the measurements were taken incorrectly“ normalerweise den folgenden Fehler melden:

 src/content/blog/myfile.mdx
 188:52  error  Don't start a sentence with     write-good.So 
                'So '.                                        

✖ 1 error, 0 warnings and 0 suggestions in 38 files.

Um für diesen spezifischen Fall die Prüfung abzuschalten, ist die entsprechende Zeile mit einem Kommentar zu umfassen:

{/*  */}

So the experiment failed because the measurements were taken incorrectly

{/*  */}

Zu beachten ist dabei, dass die beiden Kommentar-Tags und die betroffene Zeile durch einen Zeilenumbruch getrennt sein müssen. Da es sich zudem um MDX-Dateien handelt, müssen die Zeilen erst mit einem JSX-Kommentarblock umschlossen werden, damit der Server nicht meckert, und anschließend mit einem HTML-Kommentarblock, damit Vale diesen erkennt. Darüber hinaus benötigt Vale – mit folgenden beiden Zeilen in der vale.ini – einen Hinweis, dass MDX-Dateien letztlich auch als Markdown-Dateien zu behandeln sind:

[formats]
mdx = md

Im Falle kompletter Textblöcke oder wenn der Grund der Deaktivierung der Vale-Regel benannt werden soll, ist es ebenfalls möglich, nur einzelne Regeln abzuschalten:

{/*  */}

So the experiment failed because the measurements were taken incorrectly

{/*  */}