關於教學課程的問題

2022 年 3 月 8 日，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 容器內部進行開發。這使得擁有完全可攜式、完全設定的開發環境成為可能，您可以隨時啟動或關閉它。然後，您可以將該環境提供給其他人，而只需要一組組態檔。

但是，您要如何在容器內部進行開發呢？容器不像具有 UI，您可以在其中直接啟動 VS Code。

VS Code 的 Dev Containers 擴充功能正是做到這一點。它既包含將 Docker 容器設定為開發環境的機制，也允許您從 VS Code 連線到該環境。它的運作方式是在容器內安裝一個小型伺服器元件，您的本機 VS Code 會與其通訊。然後，您就可以像在本機開發一樣進行開發，但 VS Code 會連接到容器環境，而不是您的本機環境。

為了建立容器化開發環境，您通常需要了解一些關於 Docker 的知識。很多人都了解，但很多人不了解（你看不到我，但我的手舉起來了），因此該擴充功能試圖盡可能地抽象化容器設定流程。我設定了一個新的 Python 容器。精靈會引導您選擇基礎映像和 Python 版本。然後，它讓您有機會透過選擇器清單將其他軟體新增到映像。在本例中，我新增了 Azure CLI、Dotnet CLI 和 PowerShell…

此流程會將 .devcontainer 資料夾以及必要的 Dockerfile 新增到此專案。它還新增了一個 devcontainer.json 檔案，這是一個用於定義開發容器各個方面的標準，例如應該安裝哪些擴充功能、容器建置後應該執行哪些設定命令等等。由於您可以完全控制環境及其設定，因此您可以自動化幾乎所有內容 - 包括相依性安裝、程式庫版本等等。

透過這種方式，可以真正地將一個完整、隨時可用的環境交給某人，而無需額外的設定步驟或因 Ruby gem 而引發的存在危機。

有些人已經在使用基於開發容器的方法，讓他們的使用者能夠快速開始使用原本非常複雜的環境。Laravel PHP 框架就是一個很好的例子。

Laravel 解決方案

Laravel 是一個適用於 PHP 的開放原始碼 MVC 框架。它非常全面，因為它還包括物件關聯對應 (ORM)、直接資料庫存取、封裝系統等等。Laravel 可以做很多事情。為了體驗它，您在開始時真的需要至少有一個資料庫。通常這會要求使用者不僅安裝 PHP，還要安裝資料庫 - 通常是 MySQL。當使用者只是想試用您的框架時，這是一個相當大的要求。

Laravel 透過容器化開發環境和一個名為 Sail 的工具來解決這個問題。若要從頭開始使用 Laravel、MySQL Server 和 Redis 快取，您只需要執行一個命令...

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

這會建立一個包含 docker-compose 檔案的新專案。此檔案設定了三個容器 - 應用程式容器、MySQL 容器和 Redis 容器。您不必了解任何關於容器或這三種服務的知識。Sail 為您抽象化了所有這些。然後，您執行 Sail 命令來啟動環境...

    ./vendor/bin/sail up

範例應用程式只需執行即可。無需安裝 PHP。無需 Laravel。無需相依性解析步驟。立即成功。

我指定我們的專案具有 MySQL Server 和 Redis 快取，因此當專案啟動時，我們實際上會獲得三個容器。我們可以使用 VS Code 的 Docker 擴充功能 來查看。

這些容器透過網路連接在一起，以便我們可以從應用程式容器呼叫 MySQL 或 Redis 快取容器。

如果您將互動式終端機連接到 sail-8.1/app container，您將在 /var/www/html 資料夾中看到您的專案。Docker 會將專案從您的機器「掛載」到容器中，因此您在開發時所做的任何變更都會在您重新整理時反映在應用程式中。

新增開發容器

也新增了對 Dev Containers 擴充功能的支援。若要將適當的開發容器組態新增到此專案，您可以 scaffold 同一個專案並新增 &devcontainer 旗標。

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

請注意，如果您想將開發容器新增到現有的 Sail/Laravel 專案，您可以執行 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 的教學課程不一定比任何其他課程短，但重要的是，如果您跳到程式碼並只執行命令，它就能運作。開發容器使這成為可能。現在，如果我們能找出如何為我們自己的 使用 Docker 容器作為 Visual Studio Code 的開發環境 教學課程建立開發容器就好了…

祝您編碼愉快！

Burke Holland (@burkeholland)