Zeitersparnis und weniger doppelter Arbeitsaufwand mit DRY-Code

Programmierer haben ein Sprichwort, das ihnen hilft, den Code zu vereinfachen und Duplikationen zu vermeiden: „Don‘t repeat yourself“ (DRY) – „Wiederhole dich nicht“. Dies ist ein hilfreicher Ratschlag, um sich daran zu erinnern, häufig verwendete Codebits nach dem Single-Source-Prinzip in separate Dateien zu packen, die an verschiedenen Stellen eingefügt werden können. Das Befolgen des DRY-Prinzips verkürzt die Zeit, die für Updates an unterschiedlichen Stellen benötigt wird, und verringert Fehler. 

Es hat sich herausgestellt, dass dieser Ratschlag durchaus auch für das Dokumentationsteam von Fastly nützlich ist, dem ich angehöre. Da wir bestimmte Sätze und Formulierungen dutzende Male in unserer technischen Dokumentation verwenden, haben wir es als sinnvoll erachtet, einige dieser Formulierungen, auf die wir für mehrere Leitfäden zurückgreifen können, an einer einzigen Stelle zusammenzufassen. Dies hilft uns, unsere Dokumentation zu standardisieren, Kopier- und Einfügefehler zu minimieren und einige der Schwierigkeiten zu beseitigen, die mit Updates von Dokumenten aufgrund von Schnittstellenänderungen verbunden sind. Das führt dazu, dass wir schneller auf Änderungen reagieren und Ihnen die Updates schneller zur Verfügung stellen können. Außerdem hilft es uns auch, übersetzte Versionen unserer Dokumentation zu erstellen. Durch die Verwendung von Inhalten aus einer einzigen Datenquelle konnten wir schnell vom Englischen ins Japanische übersetzen und problemlos weitere Sprachen hinzuzufügen.

Und weil wir das so praktisch finden, möchte ich Ihnen einfach einmal zeigen, wie wir das gemacht haben – nur für den Fall, dass es auch für Ihren Workflow nützlich sein kann. Los gehts. 

Um das DRY-Prinzip einzuhalten, nutzten wir eine integrierte Funktion in unserem Programm Jekyll, das statische Websites generiert. Jekyll bietet eine Möglichkeit zum Single-Sourcing von Inhalten, die Datafiles genannt wird. Damit konnten wir Dateien erstellen, die Schlüssel:Wert-Paarungen enthalten, die wir als DRY-Schlüssel bezeichnen. 

DRY-Schlüssel zu erzeugen, war ganz leicht. Wir haben einfach ein _Datenverzeichnis in unserem Repository und eine YML-Datei zum Speichern der DRY-Schlüssel erstellt – eine für englische DRY-Schlüssel (en.yml) und eine für japanische DRY-Schlüssel (ja.yml). In jeder YML-Datei haben wir die DRY-Schlüssel in Schlüssel:Wert-Paarungen angelegt. Beispiel:

my-dry-key: “Insert text for DRY key.”

Hinweis: Beide YML-Dateien haben denselben Schlüsselnamen, aber der Wert wird in die Zielsprache übersetzt. 

Schwieriger war es, zu bestimmen, welcher Text in DRY-Schlüssel umgewandelt werden sollte. Wir haben uns entschieden, DRY-Schlüssel für die Überschriften der Warnhinweise zu erstellen, die überall auf der Doku-Seite zu finden sind, da auf diese sehr oft verwiesen wird:

alert-leader-tip: "TIP" 
alert-leader-note: "NOTE"
alert-leader-important: CAUTION
alert-leader-warning: "WARNING" 

Außerdem haben wir DRY-Schlüssel für die Schritte erstellt, auf die auf der gesamten Dokumentationsseite am häufigsten verwiesen wird. Diese hier kommen Ihnen wahrscheinlich bekannt vor: 

step-login: "Log in to the Fastly web interface."
step-login-configure: "Log in to the Fastly web interface and click the **Configure** link."
step-login-account: "Log in to the Fastly web interface and click the **Account** link from the [user menu](/en/guides/about-the-web-interface-controls#about-the-user-menu.Your account information appears."
step-select-service: "From the **All services** page, select the appropriate service.You can use the search box to search by ID, name, or domain."
step-click-edit: "Click the **Edit configuration** button and then select the option to clone the active version.The Domains page appears."
step-click-origins-tab: "Click the **Origins** link.The Origins page appears."
step-click-settings-tab: "Click the **Settings** link.The Settings page appears."
step-click-content-tab: "Click the **Content** link.The Content page appears."
step-activate-deploy: "Click the **Activate** button to deploy your configuration changes."

Wie sieht das in der Praxis aus? Um einen DRY-Schlüssel in der Dokumentation zu verwenden, referenzieren wir ihn einfach wie folgt in einem Liquid-Tag:  {% t my-dry-key %}.

Unser nutzerdefiniertes Jekyll Plugin liest jedes DRY-Tag und gibt den Wert des DRY-Schlüssels aus. Nehmen Sie zum Beispiel diesen Abschnitt aus der Anleitung zum Hochladen von individuellem VCL: 

Hier ein kurzer Blick hinter die Kulissen dieser Anleitung:

1.  {% t step-login %}
2.  {% t step-select-service %}
3.  {% t step-click-edit %}
4.  Click the **Custom VCL** tab.The Custom VCL page appears.
5.  Click the **Upload a new VCL file** button.The Upload a new VCL file page appears.

Das t zeigt an, dass der Code (durch etwas Zauberei hinter den Kulissen) die Sprache der Seite verwenden sollte, die die entsprechende übersetzte Version des DRY-Textes bekommen soll. Übersetzungen sind kostspielig, da die meisten Übersetzungsservices pro Wort abrechnen. Die japanischen DRY-Schlüssel helfen uns, Übersetzungskosten zu sparen, denn wir zahlen nur für die einmalige Übersetzung einer Formulierung, die dann aber an mehreren Stellen verwendet werden kann.

Als wir die DRY-Schlüssel einführten, mussten wir mehrere Such- und Ersetzungsvorgänge durchführen, um die DRY-Schlüssel an der richtigen Stelle in der Dokumentation einzufügen. Wenn sich nun aber etwas im Fastly Interface ändert, sparen wir Zeit, da wir nur eine bestimmte Stelle aktualisieren müssen, damit die Änderung auf der gesamten Website erscheint. Dies hilft uns, Ihnen Updates schneller bereitzustellen und die Gefahr zu verringern, Fehler zu machen oder eine Anleitung, die aktualisiert werden müsste, zu übersehen. 

Außerdem können wir dank dieses Systems besser skalieren, wenn wir uns entscheiden, neue Übersetzungen für unsere technische Dokumentation hinzuzufügen. Alles, was wir tun müssen, ist, die bestehende DRY-Schlüsseldatei zu nehmen, sie zu kopieren und umzubenennen, und dann diese Schlüsselwerte übersetzen zu lassen. 

Um unser selbstentwickeltes Übersetzungsprogramm genauer zu erklären, ist schon noch etwas mehr Aufwand nötig. Heben wir uns das für einen zukünftigen Blogbeitrag auf!