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. Mit `ReadTheDocs`_ kann auch ein entsprechendes Abzeichen
(engl.: Badge) angezeigt werden: .
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.
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