So automatisieren Sie den Dokumentations-Workflow für Entwickler

Um dieses Tutorial optimal nutzen zu können, sollten Sie vertraut sein mit: Git, GitHub und Linux sowie der Befehlszeile.

Warum sollten Sie sich um hochwertige Dokumentation kümmern?

Viele Teams kämpfen mit dem Schreiben von Dokumentationen . Wenn Sie ein Framework überprüfen, ist die Dokumentation oft veraltet oder unklar. Dies kann zu interner Frustration führen, wenn ein Teammitglied versucht, eine Funktion hinzuzufügen, aber aufgrund schlechter Dokumentation nicht versteht, wie die aktuelle Funktion funktioniert. Dies kann zu unproduktiven Stunden am Arbeitsplatz führen.

Eine schlechte Dokumentation beeinträchtigt auch ein gutes Kundenerlebnis. Laut Jeff Lawson, Autor von „ Ask Your Developer “ und Gründer von Twilio, ist die Dokumentation die ultimative Werbung für technische Interessengruppen , wenn Sie eine API als Produkt verkaufen. IBM hat eine Studie über die Bedeutung der Dokumentation durchgeführt, und 90 % der Befragten gaben zu, dass sie ihre Kaufentscheidungen auf der Grundlage der Qualität der Dokumentation eines Produkts getroffen haben.

Das Schreiben einer guten Dokumentation ist wichtig für das Entwickler- und Kundenerlebnis.

Wenn die Dokumentation so wichtig ist, warum räumen Entwicklungsteams ihr dann die Priorität ein?

Das Schreiben von Dokumentation kann Entwickler aus dem „Fluss“ reißen. Die Dokumentation befindet sich oft außerhalb der Hauptcodebasis und ist umständlich zu finden und zu aktualisieren. Das Einfügen in eine Excel-Tabelle oder ein proprietäres CMS ist nicht ungewöhnlich.

Die Automatisierung der Dokumentation und die Verbesserung des Dokumentationsworkflows beheben dieses Problem.

Dokumentation auf hohem Niveau automatisieren

Was bedeutet die Automatisierung der Dokumentation? Es bedeutet, gängige Softwareentwicklungspraktiken zu übernehmen. Wenn Sie die Dokumentation automatisieren, sind Sie:

• Schreiben Sie Ihre Dokumentation in Markdown;
• Verwenden einer Pipeline für kontinuierliche Integration und kontinuierliche Bereitstellung (CI/CD), um Aufgaben wie das Korrigieren von Fehlern und das Bereitstellen von Updates auszuführen (in diesem Tutorial werden wir GitHub-Aktionen hervorheben);
• Implementieren von Tools wie Vale, um einen Styleguide durchzusetzen und häufige grammatikalische Fehler zu korrigieren.

Die Styleguides

Bevor Sie Tools wie Vale und GitHub Actions verwenden, um den Styleguide zu automatisieren, nehmen wir uns einen Moment Zeit, um zu definieren, was genau ein Styleguide ist.

Kennen Sie das Gefühl, wenn Sie Dokumentationen schreiben und etwas nicht stimmt? Ihre Erklärungen passen nicht zum Rest der Dokumentation, aber Sie können nicht genau beschreiben, warum sie falsch sind. Das Schreiben erklärt das Konzept, aber es scheint nicht zu passen.

Wenn Sie dieses Gefühl bekommen, könnten Ihre Stimme und Ihr Tonfall falsch sein . Die Verfeinerung von Stimme und Ton ist eine Möglichkeit, das Schreiben zusammenhängend klingen zu lassen, selbst wenn Sie Dokumentationen entwickeln, die von den QA-, Engineering- und Produktteams bearbeitet wurden. Nachfolgend finden Sie ein Beispiel für einen Styleguide der Stadtbusanwendung TAPP aus dem Buch „ Strategic Writing for UX “ von Torrey Podmajersky.

TAPP ist eine Transitanwendung (für Busse und Bahnen). Die Kopfzeile der Tabelle verkündet die Werte von TAPP als Unternehmen, effizient, vertrauenswürdig und zugänglich zu sein. Die linke Seite der Tabelle listet die verschiedenen Teile auf, die vom Styleguide abgedeckt werden: Konzepte, Vokabular, Ausführlichkeit, Grammatik und Zeichensetzung.

Zusammen ergeben diese einen Styleguide . Die Überschrift stellt die Werte vor und die linke Seite der Tabelle zeigt die verschiedenen Komponenten, die Sie in jedem schriftlichen Material finden würden: Vokabular, Grammatik und Zeichensetzung. Das Schöne an diesem Styleguide ist, dass Ingenieure und Texter genau wissen, welche Groß- und Kleinschreibung zu verwenden und welche Satzzeichen zu verwenden sind, um die Markenidentität von Tapp zu fördern.

Styleguide für technisches Schreiben

Nicht alle Styleguides liegen in Tabellen vor. Microsoft hat eine ganze Website, die als umfassender Leitfaden dient und alles von Akronymen über voreingenommene Kommunikation bis hin zu Chatbots abdeckt. Microsoft ist natürlich nicht das einzige Unternehmen, das einen Styleguide hat. Google hat auch einen.

Das Problem mit Styleguides

Styleguides sind ein guter Ausgangspunkt für Unternehmen, die es mit der Dokumentation ernst meinen. Sie lösen einen Großteil der Verwirrung, die Entwickler möglicherweise darüber haben, wie genau sie über ein wichtiges Feature schreiben sollen, das sie herausbringen.

Das Problem mit Styleguides besteht darin, dass sie den Schreibprozess stören. Viele Autoren, mich eingeschlossen, machen sich nicht die Mühe, jedes Mal, wenn sie eine Frage haben, mit dem Schreiben aufzuhören und in den Styleguide zu schauen. Manchmal ist ein Styleguide umständlich und zu schwer zu referenzieren – zum Beispiel ist der Microsoft Styleguide über tausend Seiten lang!

Linters und CI/CD zur Dokumentation

Wenn Sie Programmierer sind, sind Sie wahrscheinlich mit Linters vertraut. Linters sind ein idealer Weg, um Codierungsstandards in Ihrem Team durchzusetzen. Genauso verhält es sich mit der Dokumentation. Mit der Erstellung eines Linters setzen Sie einen Qualitätsmaßstab für Ihre Dokumentation. In diesem Tutorial verwenden wir den Vale-Linter.

Die Verwendung einer Art Dokumentationsautomatisierung neben einem Linter ist üblich. Wenn wir in diesem Zusammenhang von Automatisierung sprechen, beziehen wir uns auf den CI/CD-Workflow (Continuous Integration and Continuous Deployment). CI automatisiert das Erstellen und Testen von Dokumentationen . CD automatisiert die Freigabe von Code.

Sie können viele verschiedene Arten von Apps verwenden, um einen CI/CD-Workflow zu implementieren. In diesem Tutorial werden wir GitHub-Aktionen verwenden, um unseren Dokumentations-Linter auszuführen. GitHub Actions führen CI direkt in einem GitHub-Repository aus, sodass keine Drittanbieteranwendung wie CircleCI oder Travis verwendet werden muss.

Schließlich sind GitHub -Aktionen ereignisgesteuert , was bedeutet, dass sie ausgelöst werden, wenn etwas passiert, z. B. wenn jemand eine Pull-Anforderung oder ein Problem schreibt. In unserem Beispiel tritt eine GitHub-Aktion auf, wenn jemand Änderungen an seinen Hauptzweig pusht.

GitHub-Aktionen

Erstellen Sie zunächst ein GitHub-Repository. Erstellen Sie dann lokal einen Ordner und cd hinein.

 mkdir automated-docs cd automated-docs

Sobald Sie sich im Ordner befinden, initialisieren Sie das Verzeichnis für Git.

 git init

Nachdem Sie das Repository initialisiert haben, erstellen Sie ein Workflow-Verzeichnis für Ihren Ordner.

 mkdir .github/ && cd .github/ && mkdir workflows/ && cd workflows/

In Workflows speichern wir alle unsere GitHub-Aktionen. Nachdem Sie einen workflows Ordner erstellt haben, erstellen Sie einen neuen Workflow. Wir werden diesen Workflow vale.yml .

 touch vale.yml

Vale.yml ist eine YAML-Datei. In diese Workflow-Datei werden wir Aktionen und Jobs aufnehmen.

Öffnen Sie nun vale.yml in Ihrem bevorzugten Texteditor.

 nano vale.yml

Kopieren Sie Folgendes und fügen Sie es in vale.yml , und lassen Sie uns den Kontext und die Syntax durchgehen.

 # This is a basic workflow to help you get started with Actions name: CI # Controls when the workflow will run on: # Triggers the workflow on push or pull request events but only for the main branch push: branches: [ main ] pull_request: branches: [ main ] # Allows you to run this workflow manually from the Actions tab workflow_dispatch: # A workflow run is made up of one or more jobs that can run sequentially or in parallel jobs: # This workflow contains a single job called "build" build: # The type of runner that the job will run on runs-on: ubuntu-latest # Steps represent a sequence of tasks that will be executed as part of the job steps: # Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it - uses: actions/checkout@v2 # Runs a single command using the runners shell - name: Run a one-line script run: echo Hello, world! # Runs a set of commands using the runners shell - name: Run a multi-line script run: | echo Add other actions to build, echo test, and deploy your project. env: GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}}

• name
  Dies ist der Name oder wie wir unseren Workflow nennen. Es ist eine Schnur.
• on
  Dies steuert den Workflow und die Trigger.
• jobs
  Hier richten und steuern wir unser Handeln. Wir wählen die Umgebung aus, in der unsere Aktionen ausgeführt werden – normalerweise ist es eine gute Wahl, Ubuntu zu verwenden. Und hier werden wir unsere Aktionen hinzufügen.

GitHub hat eine Anleitung zu allen anderen Workflow-Syntax und -Variablen, falls Sie neugierig sind.

In diesem Abschnitt haben wir:

• gelernt, was GitHub-Aktionen sind,
• unseren ersten GitHub-Workflow erstellt,
• die wichtigsten Teile einer GitHub-Workflow-YAML-Datei identifiziert.

Als Nächstes werden wir unseren GitHub-Workflow für die Verwendung von Vale anpassen.

Richten Sie Vale in der GitHub-Aktionsdatei ein

Nachdem wir die Basis-Workflow-Datei kopiert haben, ist es an der Zeit, sie anzupassen, damit wir mit der Verwendung von Vale-Aktionen beginnen können. Als erstes müssen Sie den Namen der YAML-Datei in Docs-Linting .

 # This is a basic workflow to help you get started with Actions. name: Docs-Linting

Als Nächstes wollen wir den Vale-Test ausführen, sobald jemand seine Änderungen an den Hauptzweig auf GitHub gepusht hat . Wir möchten nicht, dass der Test ausgeführt wird, wenn jemand eine Pull-Anfrage erstellt, also löschen wir diesen Teil der YAML-Datei.

 on: # Triggers the workflow on push or pull request events but only for the main branch push: branches: [ main ]

Der Abschnitt „ jobs “ ist der Hauptteil der Workflow-Datei und für die Ausführung der GitHub-Aktionen verantwortlich.

 jobs: build: runs-on: ubuntu-latest steps: - name: Checkout uses: actions/checkout@master

Diese Aktionen werden auf der neuesten Version von Ubuntu ausgeführt. Die Checkout -Aktion checkt das Repository aus, damit der GitHub-Workflow darauf zugreifen kann.

Jetzt ist es an der Zeit, unserem GitHub-Workflow eine Vale-Aktion hinzuzufügen.

 - name: Vale uses: errata-ai/[email protected] with: debug: true styles: | https://github.com/errata-ai/write-good/releases/latest/download/write-good.zip https://github.com/errata-ai/Microsoft/releases/latest/download/Microsoft.zip env: GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}}

Wir haben unsere Aktion Vale genannt. Die uses -Variable zeigt an, welche Version von Vale wir implementieren werden – idealerweise sollten wir die neueste Version verwenden. In der Variable with setzen wir debug auf true .

Der styles -Bereich gibt uns die Möglichkeit, Vale einen Styleguide hinzuzufügen. In diesem Beispiel verwenden wir write-good und den offiziellen Styleguide von Microsoft. Denken Sie daran, dass wir auch andere Styleguides verwenden können.

Der letzte Teil dieser GitHub-Aktion ist env . Um diese GitHub-Aktion auszuführen, müssen wir ein geheimes Token einfügen.

So sollte das Ergebnis aussehen:

 # This is a basic workflow to help you get started with Actions. name: Docs-Linting # Controls when the action will run. on: # Triggers the workflow on push or pull request events but only for the main branch push: branches: [ main ] # Allows you to run this workflow manually from the Actions tab workflow_dispatch: jobs: prose: runs-on: ubuntu-latest steps: - name: Checkout uses: actions/checkout@master - name: Vale uses: errata-ai/[email protected] with: debug: true styles: | https://github.com/errata-ai/write-good/releases/latest/download/write-good.zip https://github.com/errata-ai/Microsoft/releases/latest/download/Microsoft.zip env: GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}}

Nachdem Sie die Änderungen vorgenommen haben, speichern Sie die Datei, übergeben Sie sie an Git und übertragen Sie Ihre Änderungen an GitHub.

 git add .github/workflows/vale.yml git commit -m "Added github repo to project" git push -u origin main

Um es noch einmal zusammenzufassen, in diesem Abschnitt haben wir:

• löste die Aktion aus, wenn wir neuen Code in den main pushen;
• Vale-Aktion hinzugefügt, debug auf true gesetzt und Styleguides identifiziert;
• ein GitHub-Token hinzugefügt;
• Änderungen übernommen und auf GitHub gepusht.

Im nächsten Abschnitt erstellen wir eine Vale-Konfigurationsdatei.

Vale-Konfigurationsdatei einrichten

Wechseln Sie zum Stammverzeichnis Ihres Projektverzeichnisses und touch .vale.ini . Öffnen .vale.ini in einem Texteditor. Kopieren Sie Folgendes und fügen Sie es in .vale.ini :

 StylesPath = .github/styles MinAlertLevel = warning [formats] Markdown = markdown [*.md] BasedOnStyles = write-good, Microsoft

• StylesPath = .github/styles
  Der StylesPath gibt den Pfad der Vale-Stile an.
• MinAlertLevel = warning
  Die minimale Warnstufe zeigt den Schweregrad von Warnungen an. Die Optionen sind suggestion , warning und error .
• [formats]
Markdown = markdown setzt das Format auf Markdown.
• [*.md]
  Die Konfiguration BasedOnStyles = write-good, Microsoft führt write-good und den Microsoft-Styleguide auf allen Markdown-Dateien aus, die mit .md enden.

Diese Einrichtung ist das absolute Minimum. Wenn Sie mehr über die Konfiguration von Vale erfahren möchten, gehen Sie zur Dokumentation.

Wenn Sie mit den Änderungen fertig sind, speichern Sie die Datei, übertragen Sie sie und übertragen Sie sie an GitHub.

 git add .vale.ini git commit -m "Added Vale config file" git push -u origin main

In diesem Teil haben wir die Interna einer Vale-Konfigurationsdatei kennengelernt. Jetzt ist es an der Zeit, eine Beispieldokumentation zu erstellen.

Erstellen der Dokumentation und Auslösen der Vale GitHub-Aktionen

Jetzt ist es an der Zeit, Vale und GitHub Actions in Aktion zu sehen! Wir erstellen eine Markdown-Datei und füllen sie mit Text. Und wir werden unseren Text von DeLorean Ipsum bekommen.

Wechseln Sie zum Stammverzeichnis Ihres Projekts und touch getting-started.md . Sobald Sie die Datei „Erste Schritte“ erstellt haben, gehen Sie zu DeLorean getting-started und erstellen Sie einen Dummy-Text für Ihre Dokumentation. Kehren Sie dann zu Ihrem Texteditor zurück und fügen Sie den Text in getting-started-md .

 # Getting Started Guide I can't play. It's my dad. They're late. My experiment worked. They're all exactly twenty-five minutes slow. Marty, this may seem a little foreward, but I was wondering if you would ask me to the Enchantment Under The Sea Dance on Saturday. Well, they're your parents, you must know them. What are their common interests, what do they like to do together? Okay. Are you okay? Whoa, wait, Doc. What, well you mean like a date? I don't wanna see you in here again. No, Biff, you leave her alone. Jesus, George, it's a wonder I was ever born. Hey, hey, keep rolling, keep rolling there. No, no, no, no, this sucker's electrical. But I need a nuclear reaction to generate the one point twenty-one gigawatts of electricity that I need. I swiped it from the old lady's liquor cabinet. You know Marty, you look so familiar, do I know your mother?

Speichern Sie die Datei, übertragen Sie sie und übertragen Sie sie auf GitHub.

 git add getting-started.md git commit -m "first draft" git push -u origin main

Sobald Sie die Änderungen übertragen haben, gehen Sie zu GitHub, wo sich Ihr Repository befindet. Wechseln Sie zur Registerkarte Actions .

Auf der linken Seite sehen Sie alle Ihre Workflows. Wir haben nur einen namens Docs-Linting , den gleichen Namen, den wir in die Datei vale.yml .

Wenn wir die Dokumentation auf GitHub pushen, lösen wir die Aktion aus.

Wenn die Aktion ohne Probleme gelaufen ist, erhalten wir ein grünes Häkchen.

Klicken Sie auf „Hinzugefügte Dokumente“, um einen vollständigen Bericht zu erhalten.

Sie werden sehen, dass wir 11 Warnungen erhalten haben. Beschäftigen wir uns mit der „Wieselwort“-Warnung. Gehen Sie zurück zum Texteditor, öffnen Sie die Datei " getting-started.md " und löschen Sie das Wort "exactly".

 # Getting Started Guide I can't play. It's my dad. They're late. My experiment worked. They're all twenty-five minutes slow. Marty, this may seem a little foreward, but I was wondering if you would ask me to the Enchantment Under The Sea Dance on Saturday. Well, they're your parents, you must know them. What are their common interests, what do they like to do together? Okay. Are you okay? Whoa, wait, Doc. What, well you mean like a date? I don't wanna see you in here again. No, Biff, you leave her alone. Jesus, George, it's a wonder I was ever born. Hey, hey, keep rolling, keep rolling there. No, no, no, no, this sucker's electrical. But I need a nuclear reaction to generate the one point twenty-one gigawatts of electricity that I need. I swiped it from the old lady's liquor cabinet. You know Marty, you look so familiar, do I know your mother?

Speichern Sie die Änderungen, übertragen Sie sie auf Git und übertragen Sie die neue Version der Datei auf GitHub. Es sollte die GitHub-Aktion auslösen .

Wenn wir auf „Das Wiesel-Wort gelöscht“ klicken, sehen wir, dass wir jetzt nur noch 10 Warnungen haben und die „Wiesel-Wort“-Warnung verschwunden ist. Hurra!

Wir sind fertig, und wir haben eine Menge Boden bedeckt. In diesem Abschnitt haben wir:

• Dokumentation zu unserem Vale GitHub Actions-Repository hinzugefügt,
• hat die Vale GitHub-Aktion ausgelöst,
• einen von Vale verursachten Fehler korrigiert und die Änderung zurück auf GitHub gepusht.

Fazit

In einer Welt, die zunehmend remote wird, ist es wichtig, einer guten Dokumentation und einem guten Dokumentations-Workflow Priorität einzuräumen. Sie müssen zuerst definieren, was „gut“ ist, indem Sie einen Styleguide erstellen. Sobald Sie die Regeln Ihrer Dokumentation herausgefunden haben, ist es an der Zeit, sie zu automatisieren.

Die Dokumentation sollte wie Ihre Codebasis behandelt werden: eine lebendige Arbeit, die ständig iteriert wird und ein bisschen besser wird als bei der letzten Aktualisierung.