教學文件的問題

2022 年 3 月 8 日，Burke Holland，@burkeholland

撰寫出色的教學文件並不容易。我應該很清楚 - 我寫過很多教學文件，並非每一篇都大獲成功。

事實證明，撰寫出色的教學文件不在於您寫了什麼，而是開發人員是否能夠在不必逐字閱讀的情況下獲得成功。在本文中，我們將探討開發容器如何減少使用者可能遇到的錯誤，以及 Laravel PHP 專案如何在他們自己的教學文件中優雅地實現這一點，並產生顯著的效果。

沒有人會讀

我們自己關於如何在 Visual Studio Code 中使用開發容器的教學文件，長期以來完成率都很低 - 約為 4% 到 6%。

為了找出人們在哪裡放棄，我們進行了使用者研究，並觀察人們嘗試完成我們的教學文件。那真是一段...痛苦的經歷。

人們無法完成教學文件的原因立刻變得清晰：沒有人會讀它。人們直接跳過說明，直接進入操作步驟。不可避免地，他們會卡住，因為他們犯了一些錯誤，而如果他們閱讀了說明，本來可以避免這些錯誤。

賓州州立大學教授 John M. Carroll 在他的開創性著作《紐倫堡漏斗 - 設計實用電腦技能的極簡指令》中談到了這一點。他寫道：「[學習者] 太忙於學習，以至於無法充分利用說明。這就是理解的悖論。」

我對此深有同感，您可能也是如此。當我瀏覽教學文件時，我的眼睛會掃描程式碼區塊，因為我試圖透過實作來學習。我真的太忙於學習，以至於沒空閱讀說明。

人們不會閱讀您的教學文件。 或者至少不會像您希望的那樣多。您能做的最好的事情就是盡可能消除讀者在學習過程中可能犯錯的地方。其中一種方法是完全移除所有環境設定步驟，改用預先設定的容器環境。

容器化開發環境

任何教學文件中很大一部分通常都用於列出長長的先決條件和環境設定。我清楚地記得嘗試學習 Ruby on Rails 時，大部分時間都花在嘗試在 Windows 上正確安裝 Ruby - 想知道「gem」到底是什麼，以及為什麼它們都莫名其妙地遺失了。

容器化開發環境背後的想法是，您在 Docker 容器內進行開發。這使得擁有完全可攜式、完全設定的開發環境成為可能，您可以隨時建立或移除它。然後，您可以將該環境以一組組態檔案的形式提供給其他人。

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

VS Code 的開發容器擴充功能正是為此而生。它包含將 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 Cache，您只需要執行一個命令...

    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 Cache，因此當專案啟動時，我們實際上會獲得三個容器。我們可以使用 VS Code 的 Docker 擴充功能看到這一點。

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

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

新增開發容器

也新增了對開發容器擴充功能的支援。若要將適當的開發容器設定新增到此專案，您可以搭建相同的專案並新增 `&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 左下角的「遠端指示器」會告訴您...

在容器內開發而不是在容器外開發有一些明顯的好處。

開發環境脈絡與應用程式環境脈絡一致

當連線到容器時，您正在開發的環境脈絡與應用程式執行的環境脈絡相同。因此，您的終端機變成容器的終端機...

開發容器擴充功能還讓您更全面地了解正在發生的事情，例如哪些連接埠已轉發 - 以防您忘記應用程式在哪裡執行。

Laravel 應用程式會自動啟動，而應用程式記錄會傳輸到容器記錄。由於您可能想查看應用程式中正在發生的事情，因此開發容器擴充功能在 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)