返回新聞

OCaml.org 電子報：2023 年 4 月

歡迎來到 OCaml.org 電子報 2023 年 4 月號！如同先前的更新，本次電子報由 @sabine 和 @tmattio 共同整理。

OCaml.org 電子報概述了 OCaml.org 網站的變更，並讓您一窺幕後發生的事情。您可以在這裡找到先前發行的列表。

我們的目標是讓 OCaml.org 成為任何想開始使用 OCaml 並提高生產力的人的最佳資源。如果沒有所有協助我們審閱、修改和創建更好的 OCaml 文件之優秀 OCaml 社群成員，我們就無法做到這點。您的回饋使我們能夠更好地確定工作的優先順序，並朝著我們的目標邁進。謝謝你們！

我們在本月的工作將分為三個部分介紹

  • 學習區塊：為了確保我們專注於真正影響 OCaml 及其社群成功的變更，我們針對 OCaml 新手進行了使用者調查。這項調查使我們能夠更好地了解他們對現有網站的看法，以及他們對即將到來的變更的需求和願望。
  • 套件文件：在最近對套件區塊進行變更之後，我們繼續改進套件概述和文件頁面的可用性。
  • 一般改進：我們還致力於一般維護和改進，並將重點介紹其中的一些內容。

學習區塊

1. 使用者調查

本月，我們發布了我們在 3 月開始準備的調查。這項調查在各種平台上推廣，包括官方 OCaml Discuss 平台、Discord、LinkedIn 和 Twitter，並獲得了許多迴響：在我們必須關閉調查以充分分析結果之前，總共收到了 57 份回應。

除此之外，我們還審閱了先前對「學習」和「套件」區塊進行使用者訪談的錄音，將使用者回饋分組並確定優先順序，以便在即將進行的使用者訪談中使用。我們還在 OCaml Discuss 上提供了調查結果的公開摘要。

總體而言，我們現在非常了解應對「學習」區塊進行哪些變更，以改善 OCaml.org 上的學習體驗。我們的工作將在 5 月繼續進行，屆時將推出新的「學習」區塊的首批線框圖。

2. 文件頁面的進行中改進

除了我們正在進行的「學習」區塊高層次調整（如上所述）之外，我們還對文件進行了多項較小的改進，以持續改善文件的內容。

許多 ocaml/ocaml.org 上未完成的提取請求包含對「學習」區塊現有文件頁面的更新。我們的目標是在 5 月合併這些大多數更新。

我們非常感謝您一路以來的回饋、建議和協助。我們致力於透過在 OCaml.org 上提供高品質的內容，讓學習 OCaml 的過程順暢無阻。這是一項相當大的任務，每個人的協助對於實現這一目標至關重要。

套件文件

在套件區塊最近變更之後，我們繼續改進版面配置。值得注意的是，我們在「學習」和「套件」區塊中新增了一個小頁尾，解決了當捲動到頁尾時，固定定位的側邊欄移出畫面的問題。為了在捲動文件時更好地突顯目前作用中的區塊，我們重新設計了「套件」和「學習」區塊中的目錄 UI。

當套件總覽頁面的反向依賴項超過 100 個項目時，我們現在會將其摺疊。為了騰出空間放置即將推出的套件狀態徽章，我們根據Figma 設計，將套件區塊中的麵包屑移至主要內容區域上方。我們還更新了套件搜尋結果頁面的樣式，使其更緊湊，摺疊超過五項的作者列表，將套件標籤的樣式設定為與套件總覽頁面相同，並新增了直接前往套件文件的連結。

相關的 PR/問題

  1. 「學習」區塊和「套件」區塊現在都有一個附加在畫面底部的頁尾 (ocaml/ocaml.org#1018)。這解決了當捲動到頁尾時，固定定位的側邊欄會向上移出畫面的 UX 問題。另一種解決方案是當頁尾進入檢視範圍時縮小側邊欄，但由於複雜性和維護需求較高，最終被捨棄。

  2. 重新設計「套件」區塊和「學習」區塊中的目錄 UI，以在捲動文件時突顯目前作用中的區塊 (ocaml/ocaml.org#1094)。這更容易查看閱讀內容的進度，也更容易了解我們在較長文件中的位置。

  3. 現在，「套件」文件區塊的版面配置已加寬 (ocaml/ocaml.org#1097)，在 xl 螢幕尺寸上的間距增加。

  4. 由於一個套件可能會有數百甚至數千個反向依賴項，我們現在會在超過 100 個項目時摺疊反向依賴項區塊 (ocaml/ocaml.org#1101)。

  5. 現在，套件區塊中的麵包屑位於主要內容區域上方 (ocaml/ocaml.org#1133)，目的是在套件名稱旁邊騰出空間，放置即將推出的徽章，例如，提供建置狀態的相關資訊。

  6. 我們更新了套件搜尋結果頁面的樣式，使其更緊湊 (ocaml/ocaml.org#1134)：(a) 超過五項的作者列表會透過列出前五位作者和「et al.」來摺疊，(b) 套件標籤的樣式現在與套件總覽頁面相同，(c) 提供直接前往套件文件的連結。

在上個月，我們在將基本的套件內搜尋功能引入 OCaml.org 套件文件方面取得了進展。原型的工作正在 staging.ocaml.org 上進行（請參閱此 Discuss 文章），我們計劃在 5 月推出套件內搜尋的基本版本。

我們將以實驗性方式推出初始版本，因此可能會有一些問題，而且功能將會相當有限。我們很早就發布了這個版本，因為我們發現套件內搜尋對於套件文件的可用性至關重要。這個過程的好處是，我們能夠在稍後設計最終產品時，根據您的回饋和想法進行調整。

一般改進

我們改進了 OCaml.org 儀表板和 GitHub 動作工作流程。儀表板現在會顯示 Git commit 雜湊和記憶體消耗量（以位元組為單位）。我們致力於修正 RSS 摘要抓取工作流程，這導致能夠透過 GitHub UI 觸發執行抓取器，以及能夠在本機上執行工作流程。抓取工作流程對來源的暫時不可用性更具彈性，而且現在會分別抓取 Blog 頁面的個別摘要，並將其合併到全域摘要中。

我們目前正致力於在套件總覽頁面上公開套件的建置狀態資料。我們也在 OCaml 社群的協助下，開始為 OCaml 開發專用的「安裝」頁面。新頁面將提供有關如何快速設定 OCaml 的簡短說明，而相應的修補程式則包含對「開始使用」文件的全面修訂。

除此之外，團隊還積極解決了許多錯誤修正和生活品質改進，以提升整體使用者體驗。

相關的 PR/問題

  1. 我們改進了 ocaml.org 儀表板，以顯示目前執行個體所建置的 Git commit 雜湊 (ocaml/ocaml.org#1136)，並顯示記憶體消耗量（以位元組為單位） (ocaml/ocaml.org#1060)。為此，需要在啟用 Git 的資料夾中進行建置，這需要在部署管道上啟用「包含 Git」選項 (ocurrent/ocurrent-deployer#184)。

  2. 當引入 Git LFS 來儲存 OCaml Playground 資產時，RSS 摘要抓取（提供我們在「部落格」頁面上顯示的資料）在 1 月份中斷。我們觀察到的另一個問題是，對某些來源的 HTTP 要求會逾時 (kayceesrk/river#8)。我們致力於修正抓取工作流程，最終成功了。由於這項工作，我們現在可以享受 GitHub 動作工作流程的改進，例如能夠透過 GitHub UI 觸發執行抓取器，以及能夠在本機上執行工作流程 (ocaml/ocaml.org#1068)。隨後，抓取工作流程對來源的暫時不可用性更具彈性 (ocaml/ocaml.org#1120)，而且現在會分別抓取個別摘要並合併到全域摘要中，而不是同時抓取所有來源來建置全域摘要 (ocaml/ocaml.org#1144)。

  3. 我們正在努力於套件總覽頁面顯示套件的建置狀態資料 (ocaml/ocaml.org#977)。作為這項工作的一部分，基礎設施團隊已將 check.ocamllabs.io 遷移至 check.ci.ocaml.org (ocaml/infrastructure#40)。

  4. 為了提供 ocaml/ocaml.org 儲存庫中使用的程式語言的更好統計數據，我們現在將 vendor 檔案從統計數據中排除 (ocaml/ocaml.org#1074)。

  5. 針對搜尋下拉選單 (ocaml/ocaml.org#1069)和側邊欄 (ocaml/ocaml.org#1061)進行了一些與 AlpineJS 相關的錯誤修復和清理。

  6. 將 AlpineJS 升級至 3.12.0，HTMX 升級至 1.9.0 (解決了 ocaml/ocaml.org#877)。

  7. 我們在 OCaml 社群的協助下，開始著手建立 OCaml 的「安裝」頁面，網址為 https://discuss.ocaml.org/t/please-improve-my-draft-of-an-install-page-on-ocaml-org/11837。此頁面的目的是透過 JavaScript 進行作業系統偵測，以提供有關如何快速設定 OCaml 的簡短說明。即將推出的修補程式包含對「開始執行」文件的整體修訂，以提供更好的章節標題並釐清說明，同時消除文件中的雜訊。

  8. 針對關於套件文件建置失敗的查詢，CI 團隊協助我們調查了為何該套件的求解器失敗。結果發現，目前求解器似乎僅使用兩個 OCaml 版本：4.14 和 5.0.0。在情況改變之前，任何無法在這兩個 OCaml 版本上運作的套件，都將無法成功建置其套件文件。

  9. 一個新頁面，重點介紹 OCaml 社群過去進行的所有 Outreachy 實習 (ocaml/ocaml.org#1009)，已新增至「社群」區段。

  10. 我們改進了 HACKING.md 文件，以提及開發環境中的先決條件，並連結至 CI 建置並儲存在 Docker Hub 上的 Docker 映像檔 (ocaml/ocaml.org#1102)。此舉旨在簡化新貢獻者加入專案的流程。

  11. 重新排列了「部落格」頁面上的「精選」區段，以允許精選少於三篇文章 (ocaml/ocaml.org#1082).

  12. 修正當在套件搜尋結果頁面上搜尋空字串時發生的 Unicode 呈現問題 (ocaml/ocaml.org#1083)。

  13. 新增「Roboto Mono」作為專用的等寬字體 (ocaml/ocaml.org#1085)，以實現所有使用者程式碼區段的一致顯示。

  14. OCaml 使用者回報了文件中的錯誤。感謝您！我們立即修復了這些錯誤：(1) 解決未使用的 for 迴圈索引 i 錯誤 ocaml/ocaml.org#1084，(2) 移除對 utop 的不正確提及 ocaml/ocaml.org#1086，以及 (3) 說明如何在 utop-full 中啟用 -dtypedtree ocaml/ocaml.org#1089

  15. 我們將實驗性的 YAML 解析工具 tmattio/yoshi vendor 至 ocaml.org 儲存庫，以探索這是否是簡化目前 ocaml.org 的 ood-gen 工具的 YAML 解析方面的合適方法。

  16. 頂部導覽列中的套件自動完成搜尋輸入現在反應更快，因為已移除延遲限制 (ocaml/ocaml.org#1122)。

  17. 我們透過新增標題，讓 OCaml Playground 的分享按鈕更加顯眼 (ocaml/ocaml.org#1117)。

  18. 我們致力於實驗性的變更日誌頁面。

  19. 考量到我們的 Web 技術堆疊中存在一些未滿足的快取需求 (例如，在套件文件區段：查看許多 HTTP 請求並呈現模組樹狀結構選單)，我們聯絡了 OCaml 社群，以了解目前生態系統的狀況，以及在我們於 OCaml.org 上的工作中，是否有機會對 OCaml 生態系統做出有意義的貢獻。

  20. 有一個未完成的 PR，用於新增 WIP dev-container，這可以讓在 ocaml/ocaml.org 儲存庫上開始開發變得更容易。

  21. 文件頁面上的「貢獻」連結現在連結至內容呈現時所依據的 commit (ocaml/ocaml.org#1139)。

  22. OCaml.org 專案透過將 CODE_OF_CONDUCT.md 新增至其 GitHub 儲存庫 (ocaml/ocaml.org#1135) 並將 ocaml/ocaml.org 新增至採用者清單 (ocaml/code-of-conduct#6)，正式採用了 OCaml 行為準則。

  23. 「學習」區域的練習區段中的問題現在可以依難度篩選 (ocaml/ocaml.org#1141)。

  24. 錯誤修正：練習區段中的問題難度符號在太小的邊距中會被截斷。現在，練習區段中的問題難度符號僅在 xl 螢幕尺寸的邊距中顯示 (ocaml/ocaml.org#1138)。