Machen Sie das Schreiben der Dokumentation zu einem Teil Ihres Pull Requests

Daran sind wir alle schuld! Wir haben etwas geändert und vergessen, die Dokumentation zu aktualisieren. Selbst wenn Sie die besten Absichten haben, ist es viel zu einfach, es nicht zu tun.

Warum ist es so einfach, sie zu überspringen?

Angenommen, Sie haben etwas geändert, eine Pull-Anfrage erstellt und alle definierten Prozesse befolgt, bevor Sie die Änderung zusammenführen können. Wann ist der beste Zeitpunkt, um die Dokumentation in diesem Prozess zu aktualisieren? Wenn Sie die Dokumentation aktualisieren, während die Pull-Anfrage offen ist, ist die Dokumentation voraus. Sie bezieht sich auf einen Zustand, der möglicherweise erst dann eintritt, wenn Sie Ihre Pull-Anfrage zusammenführen. Was ist, wenn Sie sich entscheiden, nicht zusammenzuführen? Werden Sie daran denken, die Dokumentation zurückzugeben?

Der umgekehrte Weg ist ebenfalls alles andere als ideal. Bevor Sie bereit sind, die Pull-Anfrage zusammenzuführen, kann es einige Iterationen dauern. Ihre Kollegen geben Ihnen Feedback und Kommentare. Wenn Sie also Ihren Pull Request zum Zusammenführen bereit haben, sind Sie im Geiste schon fertig damit. Sie brauchen also Disziplin, um den zusätzlichen Schritt zu tun und die Dokumentation zu schreiben.

Natürlich können Sie dies zu einem Teil der Definition von "erledigt" machen und alle Arten von Prozessen darum herum entwickeln. Aber diese hängen in hohem Maße von der Professionalität des Teams selbst ab.

Machen Sie es zu einem Teil Ihres Pull Requests.

Ich habe meine Karriere als Software-Ingenieur begonnen, wo ich Konzepte wie die Kapselung gelernt habe. Die Idee ist einfach: Sie platzieren alle Dinge, die zueinander gehören, so nah wie möglich beieinander.

Lassen Sie uns dieses Konzept auf die Dokumentation unserer Lösung anwenden. Wir können die Dokumentation in unserem Git-Repository ablegen und die Logik und das Verhalten in einer Pull-Anfrage ändern. Der Entwickler kann auch alle Änderungen an der Dokumentation in dieselbe Pull-Anfrage aufnehmen. Für den Prüfer wird es dadurch einfacher. Er sieht die Codeänderungen und die Änderungen an der Dokumentation und kann den Zusammenhang zwischen beiden erkennen. Wenn ein Entwickler vergisst, die Dokumentation zu aktualisieren, können die Kollegen auch nach den Änderungen an der Dokumentation fragen. Es ist also bereits eine Win-Win-Situation!

Aber mein Publikum benutzt Git nicht!

Die meisten Unternehmen, für die ich gearbeitet habe, verwenden Confluence für ihre Dokumentation. Das muss Sie jedoch nicht davon abhalten, git zu verwenden! Sie können Ihre Markdown-basierte Dokumentation mit Confluence synchronisieren, indem Sie mark!

In diesem Beispiel verwende ich die GitHub-Aktionen, um die Synchronisierungsaktion durchzuführen, wenn wir zu unserem Hauptzweig pushen:

name: Deploy the documentation to confluence
on:
  push:
    branches:
      - main
jobs:
  Documentation:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4
        with:
          fetch-depth: 2
      - name: Setup Golang
        uses: actions/setup-go@v5
        with:
          go-version: '^1.21.13'
          cache-dependency-path: "**/go.sum"
      - name: Install dependencies
        run: go install github.com/kovetskiy/mark@latest
      - name: Sync Documentation
        env:
          MARK_SPACE: MySpace
          MARK_BASE_URL: https://xebia.atlassian.net/wiki
          MARK_USERNAME: ${{ secrets.CONFLUENCE_USERNAME }}
          MARK_PASSWORD: ${{ secrets.CONFLUENCE_PASSWORD }}
        run: |
          MESSAGE=$(git log -1 --pretty=format:"%s (by %an in %h)")
          UPDATED_DOC_FILES=$(git diff-tree --no-commit-id --name-only -r HEAD --root docs | grep '.md$' || true)
          for FILE in ${UPDATED_DOC_FILES}; do
            if [[ -e "${FILE}" ]]; then
              echo "> Sync ${FILE}";
              mark --version-message="${MESSAGE}" --drop-h1 --title-from-h1 -f ${FILE} || exit 1; echo;
            else
              echo "> Skipping ${FILE} as it was deleted in the last commit";
            fi
          done

Lassen Sie es uns in kleinere Schritte unterteilen:

• Schauen Sie sich den Code mit einer Tiefe von 2 an. So können wir die Änderungen der letzten Übertragung erkennen.
• Stellen Sie sicher, dass wir eine Golang-Umgebung haben, und wir werden die Abhängigkeiten zwischenspeichern, um den Build-Prozess zu beschleunigen.
• Markierung in der Umgebung installieren.
• Erfassen Sie die letzte Commit-Nachricht.
• Greifen Sie auf Markdown-Dateien zu, die bei der letzten Übertragung aktualisiert wurden.
• Synchronisieren Sie jede Datei, die geändert wurde, mit der Commit-Nachricht in der Confluence-Versionsverwaltung.

Ziemlich cool, oder? Wenn die Pull-Anfrage zusammengeführt wird, werden die vorgenommenen Änderungen, einschließlich der Dokumentation, übernommen, wenn sie zusammengeführt werden! Leider unterstützt dieses Tool nicht das Löschen von Seiten.

Fazit

Indem Sie die Dokumentation mit Ihrem Code kombinieren, kapseln Sie sie ein. Das macht es einfacher, sie auf dem neuesten Stand zu halten, und verbessert so die Gesamtqualität.

Wenn Sie ein Dokumentations-Ninja werden wollen, lesen Sie meinen Nachfolge-Blog?

Foto von Pixabay