チュートリアルに関する問題

2022年3月8日 Burke Holland, @burkeholland

優れたチュートリアルを書くのは簡単ではありません。私も多くのチュートリアルを書いてきましたが、その全てが大成功したわけではありません。

結局のところ、優れたチュートリアルを作成することは、何を書くかではなく、開発者が全ての単語を読むことなく成功できるかどうかに関係します。この記事では、開発コンテナがユーザーが遭遇する可能性のあるエラーをどのように減らすことができるか、そしてLaravel PHPプロジェクトが彼らのチュートリアルでこれをどのように効果的にエレガントに実装しているかを見ていきます。

誰も読まない

Visual Studio Code で Dev Containers を使用する方法に関する私たち自身のチュートリアルは、長らく完了率が低く、約 4 ～ 6% でした。

どこで人々が諦めているかを把握するため、ユーザー調査を実施し、人々がチュートリアルを完了しようとする様子を観察しました。それは…辛いものでした。

人々がチュートリアルを完了できない理由がすぐに分かりました。誰も読んでいなかったのです。人々は指示を飛ばして、直接実行手順に進んでいました。必然的に、指示を読んでいれば犯さなかったであろうエラーを犯し、行き詰まることになりました。

ペンシルバニア州立大学の教授であるJohn M. Carrollは、彼の画期的な著書『The Nurnberg Funnel - Designing Minimalist Instruction for Practical Computer Skill』でこれについて語っています。彼は「[学習者は] 指示を大いに活用するには忙しすぎる。これが意味理解のパラドックスである」と書いています。

私もこれに共感できますし、おそらくあなたもそうでしょう。チュートリアルを進むとき、私はコードブロックを探し求めて目を走らせます。なぜなら、実践することによって学ぼうとしているからです。文字通り、指示を読むには忙しすぎて学習しているのです。

人々はあなたのチュートリアルを読みません。少なくとも、あなたが望むほどは読みません。できる最善のことは、読者が学習プロセスでエラーを犯す可能性のある場所をできるだけ多く取り除くことです。その一つの方法は、事前に設定されたコンテナ環境を使用して、環境セットアップの手順を完全に排除することです。

コンテナ化された開発環境

どのチュートリアルでも、かなりの部分は通常、前提条件と環境設定の長いリストに費やされます。私は、Ruby on Railsを学ぼうとして、WindowsにRubyを正しくインストールするのにほとんどの時間を費やし、「gem」とは一体何なのか、なぜそれらがすべて何らかの形で足りないのかと悩んだことをはっきりと覚えています。

コンテナ化された開発環境の背後にある考え方は、Dockerコンテナ内で開発を行うということです。これにより、完全にポータブルで完全に構成された開発環境を、意のままに立ち上げたり、解体したりすることが可能になります。そして、その環境を構成ファイルのセットとして誰かに提供できます。

しかし、コンテナの中でどのように開発するのでしょうか？コンテナには、VS Codeを起動できるようなUIがあるわけではありません。

VS Code 用のDev Containers 拡張機能はまさにこれを行います。Docker コンテナを開発環境として構成するメカニズムと、その環境に VS Code から接続できるようにする機能の両方を含んでいます。これは、ローカルの VS Code と通信する小さなサーバーコンポーネントをコンテナ内にインストールすることで実現されます。これにより、ローカルで開発するのと同じように開発できますが、VS Code はローカル環境ではなくコンテナ環境に接続されています。

コンテナ化された開発環境を作成するには、通常、Dockerについて多少なりとも知っている必要があります。多くの人は知っていますが、多くの人は知りません（私には見えませんが、私の手は挙がっています）。そのため、拡張機能はコンテナのセットアッププロセスを可能な限り抽象化しようとします。新しいPythonコンテナをセットアップしました。ウィザードがベースイメージとPythonバージョンを選択する手順を案内します。次に、ピッカーリストを介してイメージに追加のソフトウェアを追加する機会を与えられます。この場合、Azure CLI、Dotnet CLI、PowerShellを追加します…

このプロセスにより、必要なDockerfileを含む.devcontainerフォルダーがこのプロジェクトに追加されます。また、devcontainer.jsonファイルも追加されます。これは、インストールすべき拡張機能、コンテナビルド後に実行すべきセットアップコマンドなど、開発コンテナの側面を定義するための標準です。環境とそのセットアップを完全に制御できるため、依存関係のインストール、ライブラリのバージョンなど、ほぼすべてを自動化できます。

このようにして、Ruby gemsに関する存在危機を引き起こしたり、追加のセットアップ手順を必要としない、完全で即座に使える環境を文字通り誰かに手渡すことが可能になります。

一部の人々はすでにDev Containerベースのアプローチを使用して、本来であれば非常に複雑な環境であるにもかかわらず、ユーザーが迅速に作業を開始できるようにしています。その好例がPHP用のLaravelフレームワークです。

Laravel ソリューション

Laravelは、PHP用のオープンソースMVCフレームワークです。オブジェクトリレーショナルマッパー（ORM）、直接データベースアクセス、パッケージングシステムなどを含む包括的なものです。Laravelは多くのことができます。それを体験するには、始めるときに少なくともデータベースが必要になります。通常、これにはユーザーがPHPだけでなく、データベース（通常はMySQL）もインストールする必要があります。ユーザーが単にフレームワークを試しているだけの場合、これはかなりの要求です。

Laravelは、コンテナ化された開発環境とSailと呼ばれるツールでこれに対処します。Laravel、MySQLサーバー、Redisキャッシュをゼロから始めるには、1つのコマンドを実行するだけで済みます…

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

これにより、docker-composeファイルを含む新しいプロジェクトが作成されます。このファイルは、アプリケーションコンテナ、MySQLコンテナ、Redisコンテナの3つのコンテナをセットアップします。コンテナやこれら3つのサービスについて何も知る必要はありません。Sailがこれらすべてを抽象化してくれます。次に、Sailコマンドを実行して環境を起動します…

    ./vendor/bin/sail up

サンプルアプリケーションはただ実行されます。PHPのインストールも、Laravelも、依存関係の解決手順もありません。ただ、すぐに成功します。

プロジェクトにMySQLサーバーとRedisキャッシュがあると指定したので、プロジェクトが起動すると実際に3つのコンテナが生成されます。これは、VS Code 用のDocker 拡張機能を使用して確認できます。

これらのコンテナはネットワークで接続されているため、アプリケーションコンテナからMySQLまたはRedisキャッシュコンテナを呼び出すことができます。

sail-8.1/app containerにインタラクティブターミナルを接続すると、/var/www/htmlフォルダーにプロジェクトが表示されます。Dockerはプロジェクトをあなたのマシンからコンテナ内に「マウント」するため、開発中に加えた変更は、更新するとアプリケーションに反映されます。

Dev Containers の追加

Dev Containers拡張機能のサポートも追加されました。このプロジェクトに適切なDev Container設定を追加するには、同じプロジェクトをスキャフォールドし、&devcontainerフラグを追加します。

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

既存のSail/Laravelプロジェクトにdevcontainerを追加したい場合は、php artisan sail:install --devcontainerを実行することで可能です。

これにより、同じプロジェクト構成が作成されますが、.devcontainerフォルダーが含まれます。VS Codeはそのフォルダーを自動的に検出し、プロジェクトをコンテナで再開するようにプロンプトを表示するため、必須のsail up手順をスキップできます。

VS Codeはコンテナにアタッチされるため、ローカル環境ではなくコンテナ環境の中で開発することになります。VS Codeの左下隅にあるリモートインジケーターがそれを教えてくれます…

コンテナ内での開発は、外部での開発と比較して明確な利点があります。

開発コンテキストがアプリのコンテキストと一致する

コンテナに接続すると、開発しているコンテキストがアプリケーションが実行されているコンテキストと同じになります。そのため、ターミナルはコンテナのターミナルになります…

Dev Containers拡張機能は、フォワードされているポートなど、何が起こっているかについてより完全なビューも提供します。これは、アプリケーションがどこで実行されているかを忘れてしまった場合に便利です。

Laravelアプリケーションは自動的に起動し、アプリケーションログはコンテナログにパイプされます。アプリケーションで何が起こっているかを確認したい場合、Dev Containers拡張機能はVS Codeに新しいビューを提供し、そこで実行中のすべてのコンテナを確認したり、コンテナログのストリームに接続したりできます。

開発環境のセットアップを自動化する

最高の開発者体験には、エディターのカスタマイズが含まれます。これには、エディター自体の設定や、そのままの状態では得られない体験に追加する必要がある拡張機能やその他のサポートが含まれます。

VS CodeとLaravelの場合、拡張機能はdevcontainer.jsonで推奨されていますが、自動的にインストールされないようにコメントアウトされています。これにより、ユーザーはすでに特定された一連の拡張機能から選択することができ、エディターを構成するための正しい方法を探し回る必要がなくなります。

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

読む時間を減らし、より多くのことをする

人々は読みません。そしてそれはそれで構いません。Laravelのチュートリアルは必ずしも他のものより短いわけではありませんが、重要なのは、コードにスキップしてコマンドを実行するだけで動作するということです。Devコンテナがそれを可能にします。あとは、私たち自身のVisual Studio CodeでDockerコンテナを開発環境として使用するチュートリアルのDevコンテナをどうやって作るかを見つけられればいいのですが…

ハッピーコーディング！

Burke Holland (@burkeholland)