© Andrii Torianyk / 123RF.com

Selbsttätige Stil- und Rechtschreibprüfung für Texte der technischen Dokumentation – das bietet Vale, ein Kommandozeilenwerkzeug, das sich gut in eine CI/CD-Pipeline oder andere automatisierte Workflows einbinden lässt.

In der Softwareentwicklung stellt man seit Jahren mittels automatisierter Methoden sicher, dass der Quellcode bestimmten Standards entspricht. Allein für die Art und Weise, in der er formatiert wird, gibt es zahlreiche Regelwerke. Bekannte Beispiele sind der PEP8-Styleguide von Python [1] oder die Stilvorgaben von Google [2]. In einem weitgehend automatisierten Umfeld gilt es aber darüber hinaus, auch die technische Dokumentation automatisch und regelbasiert zu verifizieren. Mit Vale [3] steht genau dafür ein Kommandozeilenwerkzeug zur Verfügung, das bei der Dokumentation hilft, Texte zu prüfen und zu verbessern.

Im Englischen wird dieser Vorgang Linting genannt, die entsprechenden Programme heißen Linter. Ursprünglich kommt der Begriff aus der Baumwollverarbeitung und bezeichnet einen Vorgang, bei dem man die langen, für Textilien verwendbaren Baumwollfasern (Lint) von den kurzen (Linter) trennt, die zu Zellstoff verarbeitet werden. Im übertragenen Sinn hilft Vale also, die technische Dokumentation flusenfrei aufzuarbeiten.

Vale ist quelloffen, plattformübergreifend verfügbar und lässt sich weitgehend an die eigenen Bedürfnisse anpassen. Es versucht, einen einheitlichen Schreibstil über mehrere Autoren hinweg sicherzustellen. Zudem kann man mit Vale auch – wenigstens im Englischen – die grammatische Korrektheit überprüfen. Dafür ist eine Open-Source-Variante von Grammarly entstanden, Openly [4], die sich in Vale integrieren lässt. Überhaupt zeichnet sich Vale durch sein Erweiterungssystem aus. So erlaubt es, einen unternehmensweiten Redaktionsleitfaden mit projektspezifischen Stilen zu erweitern. Der unternehmensweite Leitfaden wiederum kann auf externen Style Guides wie Proselint oder Joblint aufbauen.

Neben dieser Erweiterbarkeit bietet Vale weitere interessante Vorteile. Dazu gehört etwa eine bessere Unterstützung für syntax- und kontextsensitives Linting: Codeblöcke lassen sich ignorieren, bestimmte Textelemente können eine Sonderbehandlung erfahren. Vale kann so beispielsweise auf nichtssagende Link-Texte oder zu kurze Alternativtexte hinweisen. Einzelne Textabschnitte lassen sich je nach Kontext von der Überprüfung ausnehmen. Da Vale die natürliche Sprache analysiert, kann es auch vor stilistischen Unzulänglichkeiten warnen, zum Beispiel langen Schachtelsätzen oder überlangen Absätzen. Vale ist einfach zu installieren, da keine Paketverwaltung wie NPM oder PIP vorhanden sein muss. Das in Go geschriebene Programm steht in einer eigenständigen Binärdatei für Windows, MacOS und Linux zur Verfügung.

Aufgrund dieser Vorteile ist es nicht verwunderlich, dass Vale mittlerweile von vielen Organisationen und Open-Source-Projekten zur Qualitätskontrolle eingesetzt wird. So gibt es Implementierungen des Microsoft Writing Style Guide [5], des Google Developer Documentation Style Guide [6], des Write-Good-Linters [7], des Proselint-Linters [8] und des Joblint-Linters [9].

Installation

Die Installation von Vale ist denkbar einfach. Sie laden den aktuellen Release-Tarball von Github herunter, entpacken ihn und verschieben die ausführbare Datei an einen Ort, an dem das Betriebssystem sie findet. Vale lässt sich unter MacOS aber auch mit dem Kommando »brew install vale« über den Paketmanager Homebrew installieren. Nach einer erfolgreichen Installation rufen Sie das Programm auf der Kommandozeile auf.

Vale unterstützt von Haus aus die Auszeichnungsformate Github Flavored Markdown und HTML. Sie können aber jederzeit Parser für andere Formate installieren. Dazu zählen unter anderem:

• reStructuredText: Dieses Format wird durch Rst2html [10] unterstützt, das Sie entweder mit Sphinx [11] oder Docutils [12] installieren.
• Asciidoc: wird durch Asciidoctor [13] unterstützt.
• DITA: wird durch das DITA Open Toolkit [14] unterstützt.
• XML: wird durch Xsltproc [15] unterstützt.

Für das beliebte Satzprogramm TeX ist allerdings bisher keine Unterstützung geplant.

Konfiguration

Vale lässt sich äußerst flexibel konfigurieren. Das Programm sucht zunächst nach einer Konfigurationsdatei namens ».vale.ini« oder »_vale.ini« im selben Ordner, in dem die zu verbessernde Datei liegt. Wird die Konfiguration dort nicht gefunden, sucht das Tool bis zu sechs Ebenen höher im Dateibaum. Kann es die Datei dann immer noch nicht finden, fahndet es nach einer globalen Konfigurationsdatei im Home-Verzeichnis. So lassen sich auf einfachem Weg spezifische Regeln für einzelne Projekte implementieren.

Um Vale zu konfigurieren, legen Sie im Projekt die Datei ».vale.ini« zum Beispiel mit dem Inhalt aus Listing 1 an. In jedem Projekt können Sie sich die aktuelle Konfiguration anzeigen lassen (Listing 2).

StylesPath = ./docs/.vale
MinAlertLevel = suggestion
[*.{md,rst}]
BasedOnStyles = cusy

$ vale ls-config
{
  "BlockIgnores": {},
  "Checks": null,
  "Formats": {},
  [...]
  "SBaseStyles": {
    "*.{md,rst}": [
      "cusy"
    ]
  },
  "SChecks": {
    "*.{md,rst}": {}
  },
  "SkippedScopes": null,
  "Stylesheets": {},
  "StylesPath": "/Users/veit/cusy/comm/cusy-design-system/docs/.vale",
  [...]
}

Die Stilvorlagen, die Vale für seine Prüfung benutzen soll, definieren Sie im angegebenen Pfad, in unserem Fall zum Beispiel in der Datei »docs/.vale/cusy/Polite.yml« [16]. Der Aufbau der YAML-Datei ist recht übersichtlich, wie Listing 3 und Listing 4 demonstrieren.

extends: existence
message: 'Verwendet nicht "%s" in technischen Dokumentationen.'
level: error
ignorecase: true
tokens:
  - bitte
  - danke

extends: spelling
message: "Rechtschreibprüfung: '%s'"
dicpath: docs/.vale/cusy/Spelling
dictionaries:
  - de_DE_frami
level: warning
ignore: docs/.vale/cusy/ignore.txt qKE:

In den zu prüfenden Dateien selbst lassen sich je nach Markup-Format innerhalb von Kommentaren weitere Konfigurationsanweisungen angeben. So können Sie Vale für einzelne Absätze ganz abschalten oder nur einzelne Funktionen (de-)aktivieren (Listing 5).

### in HTML
<!-- vale off -->
Dieser Text soll von Vale ignoriert werden.
<!-- vale on -->
<!-- vale Style.Rule = NO -->
Dieser Text soll von Vale ebenfalls ignoriert werden.
<!-- vale Style.Rule = YES -->
### in reStructuredText
.. vale off
Dieser Text soll von Vale ignoriert werden.
.. vale on
### in Asciidoc
pass:[<!-- vale cusy.GenderBias = NO -->]
Dieser Mann wird ignoriert.
pass:[<!-- vale cusy.GenderBias = YES -->]
Dieser Mann löst einen Alarm aus.

Verwendung

Vale lässt sich auf der Kommandozeile, in Texteditoren, als Pre-Commit-Hook oder in einer CI/CD-Pipeline aufrufen. Auf der Kommandozeile gelingt der Start einfach mit »vale docs/first-steps/«.

Pre-Commit [17] ist ein Framework, das meist vor Code Reviews automatisch auf Probleme im Quelltext hinweisen soll, indem es etwa die Formatierung überprüft oder Debug-Anweisungen findet. Es lässt sich jedoch auch verwenden, um Prosatexte mit Vale zu überprüfen. Sie erweitern dazu die Datei ».pre-commit-config.yaml« im Root-Verzeichnis des Projekts zum Beispiel so, wie in Listing 6 gezeigt.

repos:
- repo: local
  hooks:
  - id: vale
    name: Vale
    description: Validate Style Guide with Vale
    language: docker_image
    entry: docker.io/jdkato/vale
    pass_filenames: true
    always_run: false
    verbose: true
    require_serial: false

Auch in einer CI/CD-Pipeline lässt sich Vale einsetzen. Sofern die Inhalte in einem Github-Repository liegen, kann man sie mit Vale überprüfen, ohne sie zunächst herunterladen zu müssen. Dazu richten Sie lediglich eine Github-Aktion ein, indem Sie zum Beispiel im Repository die Datei ».github/workflows« mit dem Inhalt aus Listing 7 anlegen.

name: Vale
on: [push]
jobs:
  prose:
     runs-on: ubuntu-latest
  steps:
  - name: Checkout
    uses: actions/checkout@master
  - name: Vale
    uses: errata-ai/vale-action@v1.4.0
    with:
      # Optional
      styles: |
        https://github.com/errata-ai/Microsoft/releases/latest/download/Microsoft.zip
        https://github.com/errata-ai/write-good/releases/latest/download/write-good.zip
      # Optional
        config: https://raw.githubusercontent.com/errata-ai/vale/master/.vale.ini
      # Optional
        files: PATH/TO/LINT
    env:
      # Required
      GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}}

In Listing 7 folgt nach dem Schlüsselwort »styles« eine durch Leerzeichen getrennte Liste von externen Stilen, die in den lokalen »StylesPath« des Repositorys installiert werden sollen. Jeder Link muss auf eine einzelne ZIP-Datei verweisen, die den jeweiligen Stil enthält. Auf »config« folgt eine einzelne, entfernte Vale-Konfigurationsdatei. Sie kann in einem anderen Repo, einem Github-Gist oder einer anderen Quelle gehostet werden.

Wenn es auch im lokalen Repository eine ».vale.ini«-Datei gibt, kombiniert das Programm die beiden Dateien nach den folgenden Regeln:

• Mehrwertige Einträge in der lokalen ».vale.ini«-Datei (etwa »BasedOnStyles«) werden mit den Remote-Einträgen kombiniert.
• Einwertige Einträge in der lokalen ».vale.ini«-Datei (zum Beispiel »MinAlertLevel«) überschreiben den entfernten Eintrag.

Das Schlüsselwort »files« gibt an, wo Vale nach Dateien für das Linting suchen soll. Es gibt vier Suchmethoden. Die Vorgabe »files: all« entspricht dem Aufruf von Vale auf der Kommandozeile. Die Methode »files: __onlyModified« überprüft nur Dateien, die in einem Pull-Request geändert wurden, »files: Pfad/zu/Lint« beschränkt sich auf die angegebene Datei oder das angegebene Verzeichnis. Das entspricht dem Aufruf »vale Pfad/zu/Lint«. Die Methode »files: ‘[“INPUT1“, “INPUT2“]’« schließlich ist das Pendant zu »vale INPUT1 INPUT2«.

Die Angabe »onlyAnnotateModifiedLines: true« kommentiert nur Zeilen, die innerhalb eines Pull-Requests geändert wurden. Das erweist sich als hilfreich, wenn man Vale in einem Repository aufruft, das (noch) viele Link-Typen enthält, die nicht alle überprüft werden sollen.

Zu guter Letzt lässt sich Vale auch in einem Texteditor verwenden, wofür es diverse Plugins gibt, für Sublime Text etwa SublimeLinter-contrib-vale [18]. Das Plugin »errata-ai.vale-server« [19] für Visual Studio Code lässt sich so konfigurieren, dass es nur eine Teilmenge der Warnungen anzeigt. Für Vim gibt es das ALE-Plugin [20]. Unter Emacs greifen Sie zur Flycheck-Extension [21], die sich mit der Konfiguration aus Listing 8 nutzen lässt.

(flycheck-define-checker vale
  "A checker for prose"
  :command ("vale" "--output" "line" "--no-wrap" source)
  :standard-input nil
  :error-patterns
    ((error line-start (file-name) ":" line ":" column ":" (id (one-or-more (not (any ":")))) ":" (message) line-end))
  :modes (markdown-mode org-mode text-mode)
  :next-checkers ((t . markdown-markdownlint-cli))
)
(add-to-list 'flycheck-checkers 'vale)

Ergebnisse

Nach der Installation und Konfiguration von Vale stellt sich nun die Frage, wie man mit den Ergebnissen der Prüfung umgeht. Das Programm unterscheidet zwischen Vorschlägen, Warnungen und Fehlern. Man kann sich an dieser Unterscheidung gut orientieren.

Bei den Vorschlägen (suggestions) handelt es sich um Tipps, die die Lesbarkeit eines Texts verbessern. So schlägt Vale zum Beispiel vor, wortreiche Phrasen zu kürzen oder zu versuchen, einen höheren Flesch-Kincaid-Score zu erreichen. Dieser Lesbarkeitsindex für die englische Sprache basiert auf der Wort- und Satzlänge.

Warnungen (warnings) sind Hinweise auf Verstöße gegen den Style Guide, die als sogenannte technische Schulden in zukünftigen Versionen behoben werden sollten. Das umfasst unter anderem Rechtschreibfehler, diskriminierende und geschlechtsspezifische Wörter sowie Abkürzungen ohne Erläuterung.

Unter Fehlern (errors) versteht Vale Verstöße gegen den Style Guide, die man sofort beheben sollte, zum Beispiel Markierungen von Konflikten beim Zusammenführen von Änderungen oder doppelte Schrägstriche in Link-Pfaden. Die Tabelle “Empfehlungen” enthält noch einige Ratschläge, wie Sie am besten mit den Ergebnissen aus Vale umgehen.

Lesbarkeitsbewertung

Vale bewertet die Lesbarkeit eines Texts mithilfe einschlägiger Metriken wie zum Beispiel dem Flesch Reading Ease Core. Weitere Metriken wie der Flesch-Kincaid Grade Level oder der Gunning-Fog-Index berechnen unter anderem aus der durchschnittlichen Satz- und Wortlänge, wie leicht oder schwer ein Text zu lesen ist. Diese Metriken kommen beispielsweise bei der Zusammenstellung von Schulbüchern zum Einsatz. Mit der Wiener Sachtextformel gibt es eine solche Metrik auch für die deutsche Sprache.

In Vale wird der Flesch Reading Ease Score so definiert wie in Listing 9 zu sehen. Das Resultat sollte idealerweise über einem Wert von 70 liegen. Man sieht, dass die Formel die Anzahl der Worte im Satz und der Silben in den Worten zur Bewertung heranzieht.

206.835 - (1,015 * (words/sentences)) - (84.6 * (syllables/words))

Da Vale zur Analyse der Silben in einem Wort mit NLP eine Sprachbibliothek verwendet, die ausschließlich auf die englische Sprache ausgerichtet ist, lassen sich mit vertretbarem Aufwand allerdings keine deutschen Metriken implementieren. Unsere Experimente mit der Wiener Sachtextformel erbrachten keine sinnvollen Ergebnisse. Als deutschsprachiger Anwender muss man also darauf hoffen, dass die Entwickler von NLP die deutschen Sprachmuster implementieren.

Es gibt weitere Funktionen in Vale, die nur für die englische Sprache zur Verfügung stehen. Die Funktion »capitalization« überprüft nach englischen Stilrichtlinien die Großschreibung in Überschriften, »sequence« kontrolliert die Reihenfolge bestimmter Worte im Satz. Bei der Nutzung anderer Funktionen wie »existence«, »substitution« und »consistency« muss man für nicht englische Texte den Parameter »nonword:true« setzen, um Wortgrenzen des Englischen zu ignorieren.

Rechtschreibprüfung

Vale prüft auch die Rechtschreibung und stützt sich dabei auf die frei verfügbaren Wörterbücher des LibreOffice-Projekts. Die Rechtschreibprüfung konfigurieren Sie wieder mithilfe einer YAML-Datei (Listing 10). Da der Umfang der Wörterbücher nicht sehr groß ist, benötigt man eine Ausnahmendatei (»ignore.txt«), in der man korrekt geschriebene Worte sammelt, die das Wörterbuch nicht enthält.

extends: spelling
message: "Rechtschreibprüfung: '%s'"
dicpath: /home/juh/.vale/cusy/Spelling
dictionaries:
  - de_DE_frami
level: warning
ignore: /home/juh/.vale/cusy/ignore.txt

Vale liefert zwar nur ein Wörterbuch für amerikanisches Englisch mit, doch lassen sich, wie im Beispiel gezeigt, andere Wörterbücher hinzufügen, zum Beispiel aus https://github.com/freedesktop/libreoffice-dictionaries. Sie installieren sie lokal etwa unter »~/Library/Spelling/de_DE_frami.dic« und referenzieren sie anschließend im Projekt in der Datei »docs/.vale/cusy/Spelling.yml«. Das Cusy-Designsystem enthält einige grundlegende Regeln für die deutsche Sprache, die als Ausgangspunkt für eigene Anpassungen dienen können.

Um Probleme wie Füllwörter, Tautologien, uneinheitliche Schreibweisen oder Gender-Bias behandeln zu können, erlaubt Vale – das ist eine seiner großen Stärken – eigene Wortlisten zu definieren. Mit ihnen lassen sich verschiedene Stilprüfungen vornehmen. Zum Beispiel kann man Vale so konfigurieren, dass es vor bestimmten Begriffen warnt. Das erfolgt wie üblich im YAML-Format (Listing 11).

extends: existence
message: "'%s' könnte ein Füllwort sein."
ignorecase: true
level: warning
tokens:
  - abermals
  - allem Anschein nach
  - allemal
  - allenfalls
  - allenthalben
[...]

Vale warnt anschließend vor Worten, die in der Regel keine neue Information transportieren. Solche Füllwörter sollten Sie – natürlich erst nach inhaltlicher Prüfung – am besten streichen. Mit weiteren Listen kann man tautologische Wortkombinationen im Text auffinden, wie etwa den berühmten weißen Schimmel. Zu den typischen Tautologien zählen etwa der “aktuelle Trend”, das “Endergebnis” und der “unbeabsichtigte Fehler”.

Eine andere Klasse von Tautologien umfasst Abkürzungen, an die man den letzten abgekürzten Begriff noch einmal anhängt, etwa bei der “PIN-Nummer” oder der “LED-Diode”. Solche sprachlichen Fehlkonstrukte sammeln Sie idealerweise in einer eigenen Datei (Listing 12), sodass Vale dazu über die Message-Funktion einen praktischen Hinweis geben kann.

extends: existence
message: "'%s' ist tautologisch"
ignorecase: true
level: error
tokens:
  - absolut (?:notwendig|essenziell)
  - aktueller Trend
  - Endergebnis
  - LED-Diode
  - PIN-Nummer
  - unbeabsichtigter Fehler
[...]

In der ersten Zeile von »tokens« zeigt das Beispiel aus Listing 12 eine Möglichkeit, mehrere Kombinationen in einer Token-Definition zu vereinigen. Vale findet auf diese Weise die Kombinationen “absolut notwendig” und “absolut essenziell”.

Mit der Vorschlagsfunktion kann man die Autoren bei der Suche nach besseren Formulierungen oder der richtigen Schreibweise unterstützen. Das kann die korrekte Schreibweise von Begriffen betreffen (zum Beispiel “E-Mail” statt “eMail”) oder auch Hinweise zu einer gendergerechteren Sprache.

Zusammenfassung

In einer Welt, die zunehmend auf Continuous Deployment und DevOps setzt, ist es wichtig, der Dokumentation einen vergleichbaren Workflow zu geben. Mit Vale steht ein Werkzeug zur Verfügung, das sich in diese Arbeitsabläufe integriert. Dabei lassen sich projektspezifische Sprachstile definieren, was bedeutet, dass sich das Prüfwerkzeug den jeweiligen Anforderungen eines Projekts anpasst und nicht umgekehrt.

Die projektspezifischen Regeln werden vom lokalen Texteditor übernommen, sodass die Regeln in der Continuous Integration mit den Regeln übereinstimmen, die der Autor lokal zur Verfügung hat. In der Praxis tun sich Autorinnen und Autoren leichter, wenn bereits der Texteditor vor Rechtschreibfehlern, Füllwörtern und falschen Schreibweisen warnt. Eine Prüfung außerhalb des Texteditors, zum Beispiel vor dem Einchecken als Pre-Commit oder im Rahmen einer CI/CD-Pipeline, reißt die Schreibenden dagegen aus ihrem Kontext.

Um den Arbeitsfluss der Autoren nicht zu stören, sollten Sie die Continuous-Integration-Prüfung toleranter konfigurieren als die Anzeige im Texteditor. Vale unterstützt das durch die Ausgabe unterschiedlicher Meldungen, die von Vorschlägen über Warnungen bis hin zu Fehlermeldungen reichen. Die CI-Prüfung sollte lediglich bei einem Fehler anschlagen. Dadurch bleibt es den Autoren überlassen, Empfehlungen und Warnungen bewusst zu ignorieren, die im Texteditor oder auf der Kommandozeile angezeigt werden.

Sie sollten bei der Konfiguration von Vale die Meldungsebenen berücksichtigen, um ein flüssiges Arbeiten zu ermöglichen. Im Rahmen einer technischen Dokumentation kann Vale beispielsweise die falsche Schreibung eines Markennamens oder ein vergessenes Trademark-Zeichen als Fehler markieren. Ein Pre-Commit-Hook würde daraufhin das Einchecken verhindern. Dagegen handelt es sich bei der Warnung vor einem Füllwort um eine Information, die der Autor anhand seines Stilempfindens interpretieren muss. Sie sollte nicht das Einchecken blockieren.

Der größte Nachteil von Vale liegt in der fehlenden Unterstützung für Deutsch und andere Sprachen. Das beginnt schon bei den zur Verfügung stehenden Wörterbüchern. Die frei erhältlichen Wörterbücher des LibreOffice-Projekts enthalten nur die gängigsten Worte, sodass beispielsweise viele Fachbegriffe als falsch markiert werden. Ohne eine selbst gepflegte Liste von Ausnahmen bleibt die Rechtschreibprüfung nahezu unbenutzbar. In LibreOffice lassen sich Ausnahmen einfach in ein Benutzerwörterbuch übertragen, im Zusammenspiel zwischen Texteditor und Vale klappt das allerdings noch nicht. Auf die für das Englische zur Verfügung stehenden Grammatik- und Lesbarkeitstests werden wir im Deutschen wohl noch eine Weile warten müssen. Bis dahin bleibt den Autorinnen und Autoren nichts anderes übrig, als ihrem Sprachgefühl zu vertrauen. (jcb)