チュートリアルの問題点

2022年3月8日 Burke Holland, @burkeholland

素晴らしいチュートリアルを書くのは簡単ではありません。私はそれを知っています - 私はたくさん書いてきましたが、すべてが素晴らしい成功を収めたわけではありません。

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

誰も読まない

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

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

人々がチュートリアルを完了できない理由がすぐに明らかになりました。誰も読んでいなかったのです。人々は指示を完全に飛ばして、アクションステップに直接進みました。必然的に、指示を読んでいれば犯さなかったであろうエラーを犯したために、彼らは行き詰まってしまいました。

ペンシルベニア州立大学のジョン・M・キャロル教授は、彼の代表的な著書『ニュルンベルク・ファネル - 実用的なコンピュータースキルのためのミニマリスト指示の設計』の中で、このことについて語っています。彼は、「[学習者]は学習に忙しすぎて、指示をあまり活用できません。これが意味づけのパラドックスです」と書いています。

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

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

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

どのチュートリアルでも、かなりの部分が通常、前提条件と環境設定の長いリストに費やされています。私は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 をめぐる存在の危機を引き起こすことなく、完全で、すぐに使用できる環境を文字通り誰かに手渡すことが可能です。

一部の人々はすでに、dev container ベースのアプローチを使用して、ユーザーが非常に複雑な環境を迅速に立ち上げて実行できるようにしています。この素晴らしい例は、PHP 用の Laravel フレームワークです。

Laravel の解決策

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

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

    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 containers はそれを可能にします。私たちの「Use a Docker container as a development environment with Visual Studio Code」チュートリアル用の dev container を作成する方法を考え出すことができれば...

ハッピーコーディング！

Burke Holland (@burkeholland)