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

2022年3月8日 by Burke Holland, @burkeholland

優れたチュートリアルを書くのは簡単ではありません。私にはよくわかります。私はたくさん書いてきましたが、そのすべてが大成功だったわけではありません。

優れたチュートリアルとは、何が書かれているかではなく、開発者が一言一句読まなくても成功できるかどうか、ということがわかってきました。この記事では、開発コンテナーがユーザーの遭遇する可能性のあるエラーをどのように減らすことができるか、そして Laravel PHP プロジェクトが独自のチュートリアルでこれをどのようにエレガントに実装し、大きな効果を上げているかを見ていきます。

誰も読まない

私たち自身のチュートリアルである Visual Studio Code で開発コンテナーを使用する方法は、長らく完了率が低く、約 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 の gem をめぐる実存的危機を引き起こすことなく、完全ですぐに使える環境を文字通り誰かに渡すことが可能です。

一部の人々は、そうでなければ非常に複雑な環境をユーザーに迅速に立ち上げてもらうために、すでに開発コンテナーベースのアプローチを使用しています。その素晴らしい例が、PHP の Laravel フレームワークです。

Laravel のソリューション

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

Laravel は、コンテナー化された開発環境と Sail と呼ばれるツールでこれに対処します。Laravel、MySQL Server、Redis Cache をゼロから始めるには、たった一つのコマンドを実行するだけです...

    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 Server と Redis Cache があると指定したので、プロジェクトが起動すると実際には3つのコンテナーができます。これは VS Code の Docker 拡張機能を使って確認できます。

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

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

Dev Containers の追加

Dev Containers 拡張機能のサポートも追加されました。このプロジェクトに適切な開発コンテナーの設定を追加するには、同じプロジェクトをスキャフォールディングし、&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 のチュートリアルは必ずしも他のものより短いわけではありませんが、重要なのは、コードに飛んでコマンドを実行するだけでうまくいくということです。開発コンテナーがそれを可能にします。さて、あとは私たち自身の Visual Studio Code を使って Docker コンテナーを開発環境として使用するチュートリアルのための開発コンテナーをどう作るか、解明できればいいのですが...

ハッピーコーディング！

Burke Holland (@burkeholland)