Testen#

Durch das Testen eurer Inhalte könnt ihr sicherstellen, dass sie sich in einem konsistenten Zustand befinden. Die Erfahrung beim Lesen wird besser und problemloser.

Continuous Integration#

Wir überprüfen systematisch, ob die Dokumentation des cusy Design-System erstellt werden kann und zeigen euch dies auch mit folgendem Abzeichen (engl.: Badge) an: Docs.

Dieses Abzeichen wird vom Dokumentationsserver Read the Docs, auf dem unsere Dokumentation des cusy Design-System veröffentlicht wird, bereitgestellt.

Weitere automatisch generierte Abzeichen findet ihr auf unserer Seite cusy Design-System mit Hinweisen zur Anzahl der Mitwirkenden, zur Aktualisierungshäufigkeit, zur Lizenz und zu Mastodon.

Solche Abzeichen lassen sich jedoch nicht nur verwenden um den Status eures Projekts zu dokumentieren, sondern auch um einen stets aktuellen Überblick über viele verschiedene Projekte zu erhalten. Ein Beispiel hierfür findet ihr in unserem PyViz-Tutorial.

Sphinx-Checks#

Siehe auch

Bemerkung

Falls ihr ein anderes Werkzeug zum technischen Schreiben verwendet, könnt ihr z.B. HTMLProofer verwenden um Links, Bilder, Titel und Tags zu überprüfen.

Code überprüfen#

Ihr könnt automatisch euren Quellcode überprüfen und ggf. auch neu formatieren lassen. Einen Überblick über solche Werkzeuge erhaltet ihr in unserem Jupyter-Tutorial unter Checker und Formatter.

Syntax überprüfen#

Es gibt auch Werkzeuge, die eure Inhalte anhand von Regeln überprüfen.

Siehe auch

Sprachstil überprüfen#

Prosa-Linters wie z.B. Vale gehen weit über Rechtschreib- und Grammatikprüfungen hinaus und betrachten auch den Sprachgebrauch: Wiederholt sich das Gesagte? Ist die Sprache zu informell? Ist die Ansprache inkonsistent? Werden unerwünschte Klischees bedient? Oder ist die Sprache sexistisch?

Vale wird von vielen Open-Source-Projekten genutzt, u.a. von

Mit Vale selbst kommen die folgenden Stile mit:

Microsoft

Eine Implementierung des Microsoft Writing Style Guide.

Google

Eine Implementierung des Styleguides für den Google developer documentation style guide.

write-good

Eine Umsetzung der vom write-good-Linter erzwungenen Richtlinien.

proselint

Eine Umsetzung der vom proselint-Linter erzwungenen Richtlinien.

Joblint

Eine Umsetzung der vom Joblint-Linter erzwungenen Richtlinien.

Ihr könnt Vale installieren mit

$ brew install vale

Wenn ihr als Dokumentationswerkzeug Sphinx nutzt, solltet ihr noch den rst2html-Parser installieren mit

$ brew install docutils

Nun könnt ihr Vale konfigurieren in .vale.ini:

StylesPath = ./styles
MinAlertLevel = suggestion

[*.{md,rst}]
BasedOnStyles = mystyles

vale.Redundancy = YES
vale.Repetition = YES
vale.GenderBias = YES

Anschließend werden die Stile definiert, u.a. in styles/MY_STYLE/Polite.yml, z.B. mit:

extends: existence
message: 'Do not use “%s” in technical documentation.'
level: error
ignorecase: true
tokens:
  - please
  - thank you

Und schließlich könnt ihr eure Dokumentation überprüfen mit:

$ vale docs/
✔ 0 errors, 0 warnings and 0 suggestions in 201 files.

Vale liefert nur ein Wörterbuch für amerikanisches-Englisch mit. Ihr könnt jedoch auch andere Wörterbücher hinzufügen, z.B. aus github.com/freedesktop/libreoffice-dictionaries. Diese könnt ihr einbinden indem ihr sie lokal zur Verfügung stellt, z.B. unter ~/Library/Spelling/de_DE.dic,aff und sie anschließend in eurem Projekt in der Datei styles/MY_STYLE/Spelling.yml referenziert:

extends: spelling
message: "Rechtschreibprüfung: '%s'"
dicpath: ~/Library/Spelling
dictionaries:
  - de_DE_frami
level: warning
ignore: styles/cusy/ignore.txt

Bemerkung

Wenn ihr den Inhalt eures GitHub-Repository mit Vale überprüfen wollt, könnt ihr eine GitHub-Action hierfür einrichten: vale-action.

Üblicherweise werden literal blocks, inline literals und code-blocks ignoriert. Ihr könnt jedoch auch Bereiche aus der Überprüfung herausnehmen mit:

.. vale off

Text, der nicht überprüft werden soll.

.. vale on

Siehe auch