Das Problem mit Tutorials

8. März 2022 von Burke Holland, @burkeholland

Ein großartiges Tutorial zu schreiben ist nicht einfach. Das sollte ich wissen – ich habe viele davon geschrieben, und nicht alle waren ein voller Erfolg.

Wie sich herausstellt, geht es bei der Erstellung eines großartigen Tutorials nicht darum, was man schreibt, sondern darum, ob Entwickler erfolgreich sein können, ohne jedes Wort lesen zu müssen. In diesem Artikel werden wir untersuchen, wie Entwicklungskontainer Fehler reduzieren können, die ein Benutzer möglicherweise begeht, und wie das Laravel PHP-Projekt dies elegant in seinen eigenen Tutorials mit großem Erfolg implementiert.

Niemand liest

Unser eigenes Tutorial zum Thema Verwendung von Dev Containers in Visual Studio Code hat seit langem niedrige Abschlussraten – etwa 4-6 %.

Um herauszufinden, wo die Leute aufgeben, führten wir Benutzerstudien durch und beobachteten, wie Leute versuchten, unser Tutorial abzuschließen. Es war ... schmerzhaft.

Es war sofort klar, warum die Leute das Tutorial nicht abschließen konnten: Niemand las es. Die Leute übersprangen die Anweisungen und gingen direkt zu den Handlungsschritten über. Unweigerlich blieben sie stecken, weil sie einen Fehler machten, den sie nicht gemacht hätten, wenn sie die Anweisungen gelesen hätten.

Der Professor der Penn State University, John M. Carroll, spricht darüber in seinem wegweisenden Buch The Nurnberg Funnel – Designing Minimalist Instruction for Practical Computer Skill. Er schreibt: „[Lerner] sind zu beschäftigt mit dem Lernen, um die Anweisungen großartig zu nutzen. Das ist das Paradoxon des Sinngebens.“

Ich kann das nachvollziehen, und Sie wahrscheinlich auch. Wenn ich ein Tutorial durcharbeite, scannen meine Augen nach Codeblöcken, weil ich durch Tun lernen möchte. Ich bin buchstäblich zu beschäftigt mit dem Lernen, um die Anweisungen zu lesen.

Die Leute werden Ihr Tutorial nicht lesen. Oder zumindest nicht so viel, wie Sie es sich wünschen würden. Das Beste, was Sie tun können, ist, so viele Stellen wie möglich zu entfernen, an denen der Leser während des Lernprozesses einen Fehler machen könnte. Eine Möglichkeit, dies zu tun, besteht darin, alle Schritte zur Umgebungsinstallation mit vorkonfigurierten Containerumgebungen vollständig zu entfernen.

Containerisierte Entwicklungsumgebungen

Ein erheblicher Teil jedes Tutorials ist normalerweise einer langen Liste von Voraussetzungen und der Umgebungsinstallation gewidmet. Ich erinnere mich deutlich daran, wie ich versucht habe, Ruby on Rails zu lernen, und die meiste Zeit damit verbracht habe, Ruby unter Windows korrekt zu installieren – und mich gefragt habe, was zum Teufel ein "Gem" ist und warum sie alle irgendwie fehlten.

Die Idee hinter containerisierten Entwicklungsumgebungen ist, dass Sie innerhalb eines Docker-Containers entwickeln. Dies ermöglicht eine vollständig portable, voll konfigurierte Entwicklungsumgebung, die Sie nach Belieben aufbauen oder abbauen können. Sie könnten diese Umgebung dann jemandem als nichts weiter als eine Reihe von Konfigurationsdateien übergeben.

Aber wie entwickelt man innerhalb eines Containers? Es ist nicht so, als hätten Container eine Benutzeroberfläche, auf der Sie einfach VS Code starten können.

Die Dev Containers-Erweiterung für VS Code tut genau das. Sie enthält sowohl den Mechanismus zur Konfiguration eines Docker-Containers als Entwicklungsumgebung als auch die Möglichkeit, sich von VS Code aus mit dieser Umgebung zu verbinden. Dies geschieht durch die Installation einer kleinen Serverkomponente innerhalb des Containers, mit der Ihr lokaler VS Code kommuniziert. Sie entwickeln dann genauso, als wären Sie lokal, aber VS Code ist an die Containerumgebung anstatt an Ihre lokale Umgebung angebunden.

Um eine containerisierte Entwicklungsumgebung zu erstellen, müssten Sie normalerweise einiges über Docker wissen. Viele Leute tun das, aber viele Leute tun es nicht (Sie können mich nicht sehen, aber meine Hand ist erhoben), daher versucht die Erweiterung, den Prozess der Container-Einrichtung so weit wie möglich zu abstrahieren. Ich habe einen neuen Python-Container eingerichtet. Ein Assistent führt Sie durch die Auswahl des Basisbildes und der Python-Version. Anschließend haben Sie die Möglichkeit, über eine Auswahlliste zusätzliche Software zum Bild hinzuzufügen. In diesem Fall füge ich die Azure CLI, Dotnet CLI und PowerShell hinzu…

Dieser Prozess fügt dem Projekt einen Ordner .devcontainer mit der erforderlichen Dockerfile hinzu. Außerdem wird eine Datei devcontainer.json hinzugefügt, die ein Standard zum Definieren von Aspekten eines Dev-Containers ist, wie z. B. welche Erweiterungen installiert werden sollen, welche Setup-Befehle nach dem Container-Build ausgeführt werden sollen usw. Da Sie die vollständige Kontrolle über die Umgebung und ihre Einrichtung haben, können Sie so ziemlich alles automatisieren – einschließlich der Installation von Abhängigkeiten, Bibliotheksversionen usw.

Auf diese Weise ist es möglich, jemandem buchstäblich eine vollständige, einsatzbereite Umgebung zu übergeben, die keine zusätzlichen Setup-Schritte oder Auslöser von existenziellen Krisen über Ruby-Gems erfordert.

Einige Leute nutzen bereits einen Ansatz, der auf Dev-Containern basiert, um ihre Benutzer schnell mit ansonsten sehr komplexen Umgebungen einsatzbereit zu machen. Ein großartiges Beispiel dafür ist das Laravel-Framework für PHP.

Die Laravel-Lösung

Laravel ist ein Open-Source-MVC-Framework für PHP. Es ist umfassend in dem Sinne, dass es auch Dinge wie einen Object Relational Mapper (ORM), direkten Datenbankzugriff, ein Paketverwaltungssystem und mehr enthält. Laravel kann viel. Und um es zu erleben, benötigen Sie zu Beginn mindestens eine Datenbank. Normalerweise müsste der Benutzer nicht nur PHP, sondern auch eine Datenbank installieren – normalerweise MySQL. Das ist eine erhebliche Anforderung, wenn ein Benutzer Ihr Framework nur ausprobieren möchte.

Laravel adressiert dies mit containerisierten Entwicklungsumgebungen und einem Tool namens Sail. Um von Grund auf mit Laravel, einem MySQL-Server und einem Redis-Cache zu beginnen, müssen Sie nur einen einzigen Befehl ausführen…

    curl -s "https://laravel.build/example-app?with=mysql,redis" | bash

Dies erstellt ein neues Projekt mit einer docker-compose-Datei. Diese Datei richtet drei Container ein – einen Anwendungscontainer, einen MySQL-Container und einen Redis-Container. Sie müssen nichts über Container oder einen dieser drei Dienste wissen. Sail abstrahiert all dies für Sie. Anschließend führen Sie den Sail-Befehl aus, um die Umgebung zu starten…

    ./vendor/bin/sail up

Die Beispielanwendung läuft einfach. Kein Installieren von PHP. Kein Laravel. Keine Schritte zur Abhängigkeitsauflösung. Sofortiger Erfolg.

Ich habe angegeben, dass unser Projekt einen MySQL-Server und einen Redis-Cache hat, daher erhalten wir tatsächlich drei Container, wenn das Projekt gestartet wird. Wir können dies mit der Docker-Erweiterung für VS Code sehen.

Diese Container sind miteinander vernetzt, sodass wir vom App-Container aus die MySQL- oder Redis-Cache-Container aufrufen können.

Wenn Sie ein interaktives Terminal mit dem sail-8.1/app container verbinden, sehen Sie Ihr Projekt im Ordner /var/www/html. Docker "mountet" das Projekt von Ihrem Computer in den Container, sodass alle Änderungen, die Sie während der Entwicklung vornehmen, in der Anwendung reflektiert werden, wenn Sie aktualisieren.

Hinzufügen von Dev Containern

Es wurde auch Unterstützung für die Dev Containers-Erweiterung hinzugefügt. Um die entsprechende Dev-Container-Konfiguration zu diesem Projekt hinzuzufügen, können Sie dasselbe Projekt schablonisieren und das Flag &devcontainer hinzufügen.

    curl -s "https://laravel.build/example-app?with=mysql,redis&devcontainer" | bash

Beachten Sie, dass Sie, wenn Sie einen Devcontainer zu einem bestehenden Sail/Laravel-Projekt hinzufügen möchten, dies tun können, indem Sie php artisan sail:install --devcontainer ausführen.

Dies erstellt die gleiche Projektkonfiguration, fügt aber einen Ordner .devcontainer hinzu. VS Code erkennt diesen Ordner automatisch und fordert Sie auf, das Projekt in einem Container erneut zu öffnen, wodurch der erforderliche sail up-Schritt übersprungen wird.

VS Code stellt eine Verbindung zum Container her, sodass Sie innerhalb der Containerumgebung entwickeln und nicht außerhalb davon. Das erkennen Sie daran, dass die Remote-Anzeige in der unteren linken Ecke von VS Code dies anzeigt…

Die Entwicklung im Container im Gegensatz dazu außerhalb davon hat einige deutliche Vorteile.

Entwicklungskontext spiegelt App-Kontext wider

Wenn Sie mit dem Container verbunden sind, ist der Kontext, in dem Sie entwickeln, derselbe wie der, in dem die Anwendung ausgeführt wird. Ihr Terminal wird also zum Terminal des Containers…

Die Dev Containers-Erweiterung gibt Ihnen auch einen umfassenderen Überblick darüber, was vor sich geht, z. B. welche Ports weitergeleitet werden – nur für den Fall, dass Sie vergessen, wo Ihre Anwendung läuft.

Die Laravel-Anwendung startet automatisch, und die Anwendungslogs werden an die Containerlogs weitergeleitet. Da Sie wahrscheinlich sehen möchten, was in der Anwendung vor sich geht, bietet die Dev Containers-Erweiterung eine neue Ansicht in VS Code, in der Sie alle laufenden Container sehen und sich mit Stream-Container-Logs verbinden können.

Automatisieren der Einrichtung der Entwicklungsumgebung

Die bestmögliche Entwicklererfahrung wird Anpassungen für den Editor beinhalten. Dies umfasst Einstellungen für den Editor selbst und alle Erweiterungen oder andere Unterstützung, die zur Out-of-the-Box-Erfahrung hinzugefügt werden müssen.

Für VS Code und Laravel werden Erweiterungen in der devcontainer.json vorgeschlagen, aber auskommentiert, sodass sie nicht automatisch installiert werden. Dies ermöglicht es dem Benutzer, aus einer Reihe bereits identifizierter Erweiterungen auszuwählen, anstatt nach dem richtigen Weg zur Konfiguration seines Editors suchen zu müssen.

    ...
    "extensions": [
        // "mikestead.dotenv",
        // "amiralizadeh9480.laravel-extra-intellisense",
        // "ryannaddy.laravel-artisan",
        // "onecentlin.laravel5-snippets",
        // "onecentlin.laravel-blade"
    ],

Weniger lesen, mehr tun

Menschen lesen nicht. Und das sollte in Ordnung sein. Die Tutorials von Laravel sind nicht unbedingt kürzer als andere, aber das Wichtigste ist, dass es funktioniert, wenn man zum Code springt und einfach die Befehle ausführt. Dev-Container machen das möglich. Jetzt müssten wir nur noch herausfinden, wie wir einen Dev-Container für unser eigenes Tutorial Verwenden eines Docker-Containers als Entwicklungsumgebung mit Visual Studio Code erstellen können…

Viel Spaß beim Programmieren!

Burke Holland (@burkeholland)