Bokeh 專案

本頁針對 Google 系列文件接受的技術撰寫專案提供詳細資料。

專案摘要

開放原始碼機構：

散景

技術文件撰寫者：

vis_verborum

專案名稱：

建立、閱讀與分享：最佳化 Bokeh 說明文件

專案長度：

標準長度 (3 個月)

Project description

建立、閱讀、分享：最佳化 Bokeh 說明文件

1. 摘要

Bokeh 是功能強大的工具，能夠使用 Python 建立以瀏覽器為基礎的互動式視覺化內容。它擁有可觀的使用者數量 (每月 Conda 下載量 502, 000 次，下載 85.5 萬次 PyPi)，還有許多協作者 (GitHub 上的 455 位貢獻者)。當然，Bokeh 提供的豐富說明文件自然也會隨時間增加，這點並不令人意外。因此，在某些地方，不一致、難以存取且持續發展。

透過 Google 的系列文件

我使用 Python 和 Sphinx 來編寫和記錄開放原始碼專案 (最近專案：PyZillow 和 PyPresseportal)。但出於特別的 Google 文件季別，是我參與新聞界的特別參與者：我在新聞編輯室工作超過 13 年，多年來擔任管理人員與提倡數位變革。除了投入自己的新聞職涯，我也必須承擔更多責任，包括設計及記錄新的數位工具和風格指南，並訓練新聞編輯室員工。

最近從歐洲遷移到美國後，我決定探索新的方式，凝聚對溝通和程式設計的熱忱。我發現技術文案是結合寫作和科技的理想組合。在本提案中，我將介紹如何使用 Google 的整季文件改善 Bokeh 的說明文件：讓製作文件及提供文件內容時更加簡單，同時方便其他人閱讀說明文件，讓他們更容易進行分享。

2. 現狀

Bokeh 的官方說明文件包含下列主要單元：

• 敘述性說明文件：安裝指南、使用手冊、開發人員指南、版本資訊
• 圖片庫和示範 (含有原始碼的互動式範例)
• 參考指南 (以文件字串為基礎的說明文件)
• 教學課程 (大量的 Jupyter 筆記本，由 mybinder.org 代管)
• IDE 的 Docstring 和模型說明
• 專案存放區中的範例和 README

此外，您還可以在 Bokeh 支援論壇和 Stack Overflow 上，找到豐富的資訊，包括 Bokeh 的開發人員主動回答使用者問題，以及 Bokeh 的 Medium 網誌。

大部分的說明文件網頁都是使用 Sphinx 建立，並且使用數種標準和自訂的 Sphinx 擴充功能。以「autodoc」和自訂「bokeh_autodoc」等副檔名為例，「參考指南」就能從 docStrings 產生。由於文件是自然擴充的文件性質，含有冗餘字詞且不一致。

分析現有說明文件時，我們發現其中一項首要考量就是缺少文件撰寫文件的明確樣式規範。Bokeh 開發人員指南包含幾項基本操作說明。不過，本文件並未針對樣式提供太多指引，特別是有關 docstring 以外的說明文件。因此，風格和結構性問題會使存取文件資訊更加困難，尤其是新手。

例如：

• 使用名詞、繁體和不常見的動詞來取代明確且強烈的動詞，導致部分文字產生不必要的複雜問題：「主要觀察是，一般用法涉及利用 chart() 函式建立繪製物件圖」。這應該重新改寫，以方便閱讀。舉例來說，「graph() 函式是最常用來建立圖表物件的函式」。
• 部分句子過長，導致難以理解：「接下來，我們可以呼叫 vbar 並將一份果子名稱因子清單當成 x 座標清單，以長條高度做為頂端座標，還可選擇任何寬度或其他要設定的屬性」。長句應拆分為較短的句子或項目符號清單。對於有失讀症或非以英文為母語的使用者，簡化句子會特別有幫助 (請參閱問題 #10160)。
• 使用「您」和「我們」的方式不一致，容易造成乾擾且令人分心：「有兩種基本方法可供使用」和「我們可以使用不同呼叫繪製一整年系列內容」 (請參閱同一頁面的兩個範例)。部分網頁對讀者的操控方式不盡相同，例如：「使用者可能需要安裝其他依附元件」或「我們可以建立更複雜的版面配置」。
• 內容拼寫錯誤、缺少多餘字詞及語態錯誤會破壞閱讀過程，並造成資訊的可信度受損：「Bokeh 可簡化基本長條圖的建立流程」或「請參閱 Glyphs 章節，瞭解使用者指南」。
• 結構不一致會對讀者造成困擾，例如在一頁提供有註解的示例，而且沒有其他網頁示例的說明。

Bokeh 的說明文件到達網頁簡短，並未涵蓋所有可用資源的資訊 (未提及豐富的 docstrings 和模型說明函式、支援論壇、示範或 Medium 網誌)。這也讓新使用者較難開始使用 Bokeh。

3. 目標

為了有效利用十週文件開發階段，我將著重於三個關鍵要素：

3.1. 改善文件建立能力

大部分的 Bokeh 說明文件是由協作者編寫的，他們會在提取要求中納入新功能和錯誤修正的說明文件。雖然我會用部分文件開發階段來編輯及重構現有文件，但著重在製定和維護說明文件未來可行的工作流程：對於貢獻者，最好盡量簡單地維持一貫且標準的文件。

我會採用以下兩種做法確保這種情況：

• 我將會擬定一套實用、簡單的樣式規範，以便包含在現有的開發人員指南中。這些指南將探討樣式、文法和結構。此外，我也會使用 Slack 等內部通訊管道，確保 Bokeh 的貢獻者瞭解樣式規範。我也會為團隊提供一對一的訓練和問答活動。
• 我會與核心團隊合作，找出一套完善的文件品質控管工具，並新增至 Bokeh 現有的 PR (提取要求) 和 CI (持續整合) 工作流程中。視團隊需求而定，這可能包括新增 pydocstyle、proselint 或 sphinxcontrib-spelling 拼字檢查工具，檢查 Bokeh 的測試套件、修訂前設定或 GitHub 動作。我在自己的其中一個開放原始碼專案中，將有效概念驗證新增至 GitHub 動作中。

3.2. 改善說明文件閱讀方式

適當的文件機制的目標是讓現有和潛在的使用者能夠輕鬆找到正確的資訊，並且盡可能有效率地使用這些資訊。

文字可用性的關鍵因素則是文字的可用性和結構：以清楚一致的方式撰寫文件，讀者不會因為分心而感到不悅，而是能夠快速獲得資訊。文件的結構簡單明瞭，方便使用者快速找到相關資訊。

我們會著重於這兩個領域，並特別重視新使用者的可用性。當中包含完整說明文件，內容以《使用者指南》為中心。此外，我也會調整說明文件到達網頁，以便更清楚地觸及不同的目標對象，並確保每位使用者都能快速找到正確的資源。

就像改善上述文件的建立方式一樣，我將著重在為未來改進奠定基礎，並持續以高標準為 Bokeh 說明文件建立良好標準。

3.3. 改善文件共用設定

更多關於 Bokeh 的討論都在第三方平台上進行。其中許多平台都會使用如 Facebook 的 OpenGraph 等中繼資料，提供豐富的連結預覽。Facebook、Twitter、LinkedIn、Slack 和 iMessage 等服務會使用 OpenGraph。Bokeh 的 Discourse 論壇也使用 OpenGraph 來呈現連結預覽。

為了使用這項技術，我會依照問題 #9792，在 Bokeh 的 Sphinx 產生的網頁中加入中繼資料。使用專屬的 Sphinx 擴充功能是最有效率的方法。幾天前，我們曾在 GitHub 發布適用於 OpenGraph 資料的 Sphinx 擴充功能第一個版本，我會用部分文件開發階段改善這個擴充功能，並配合 Bokeh 的說明文件。

我也建立了概念驗證，證明我在其中一個開放原始碼專案 PyPresseportal 中成功使用。這項擴充功能會自動收集名稱、說明、圖片和網址等相關資訊。然後將這些資訊插入 Sphinx 產生的 HTML 程式碼中，做為 OpenGraph 標記。

開發這項擴充功能的下一步，是導入自訂指令，用於手動定義 OpenGraph 中繼資料 (類似 docutil 現有的「meta」指令)。如果沒有可用的手動輸入資料，則系統自動產生的中繼資料只能當做備用資料使用。

支援結構化資料的程序相當複雜，因此，我主要著重於為 Bokeh 說明文件加入高品質的 OpenGraph 中繼資料。所有支援 OpenGraph 的作業都會同時為支援結構化資料奠定基礎。

Sphinx 和 ReadTheDocs 社群的成員都表示有興趣開發 OpenGraph 和結構化資料的擴充功能 (例如 #1758 和 #5208 的問題)，且我會確保與他們密切合作。

4. 交付項目

總結來說，以下是我預計在文件季度之外的交付項目：

• 適用於 Bokeh 貢獻者的說明文件樣式指南
• 修改 PR 和 CI 工作流程，加入自動化文件品質控管機制
• 編輯及重新建構使用手冊
• 修訂說明文件到達網頁
• 說明文件網頁包含 OpenGraph 中繼資料，以及有效的 Sphinx 擴充功能

此外，我會保留一份「文件記錄」，在個人網站/Medium 或 Bokeh 的 Medium 網誌上記錄 Google 文件季度的旅程。做為 Google 專案報表的基礎。我會盡可能以 GitHub 問題和提取要求的形式，以公開透明的方式完成所有工作。

5. 時間表

在社群凝聚階段之前：我目前已積極參與 Bokeh GitHub 存放區的數則討論，也曾與 Bokeh 擔任 Google 文件季度的導師 Bryan Van de Ven 和 Pavithra Eswaramoorthy 聯絡。我會在 Bokeh 的對話中持續互動，也會建立並發布圖表，進一步熟悉 Bokeh。

社群凝聚階段 (8 月 17 日 - 9 月 13 日)：

• 認識核心團隊，協調專案計畫並與其他導師交流
• 設定時間表和溝通管道，以便定期與導師交流及提供意見
• 積極參與 Bokeh Slack，讓所有有興趣 Bokeh 貢獻者瞭解 Google 文件季度，以及文件開發階段的目標
• 收集 Bokeh 貢獻者的意見回饋，進一步修正文件開發階段的計畫

文件開發階段

第 1 週 2014 年 9 月 - 20 日：

• 開始稽核及編輯敘述性文件
• 開始草擬樣式規範

第 2 週 (2021 年 9 月 2 日 - 9 月 27 日)：

• 繼續處理樣式規範
• 繼續編輯敘述性說明文件
• 開始重新設計說明文件到達網頁

第 3 週 (2028 年 9 月 28 日 - 10 月 4 日)：

• 完成樣式規範
• 完成說明文件到達網頁

第 4 週 5 月 10 日 - 11 日：

• 完成敘述性說明文件的編輯
• 與 Bokeh 核心團隊討論在 PR/CI 工作流程中整合用於文件品質控管的工具

第 5 週 - 10 月 10 日 - 10 月 18 日：

• 與 Slack 的 Bokeh 協作者安排問答時間，討論樣式準則、改善敘事性說明文件和 PR/CI 工作流程
• 開始將現有的 OpenGraph 中繼資料驗證概念開發成可部署的 Sphinx 擴充功能
• 根據 Bokeh 貢獻者問答時間的意見回饋，修改樣式規範

第 6 週 - 10 月 10 日 - 10 月 25 日：

• 開始測試 PR 和 CI 工作流程的文件品質控管工具
• 繼續開發中繼資料的 Sphinx 擴充功能

第 7 週 10/26 - 11 月 1 日：

• 測試 Sphinx 擴充功能
• 與 Slack 的 Bokeh 協作者進行第二次問答
• 依據第二次問答活動的意見回饋，調整交付項目

第 8 週 - 2002 年 11 月 - 11 日：

• 部署 Sphinx 擴充功能，發布更優質的敘述文件和說明文件到達網頁

第 9 週 - 2009 年 11 月 - 11 日：

• 將文件品質控管工具部署至 PR 和 CI 工作流程
• 更新並發布開發人員指南，納入樣式規範，以及 PR 和 CI 工作流程的附加內容

第 10 週，11 月 16 日 - 11 月 22 日：

• 完成其餘工作

第 11 週 - 2023 年 11 月 - 11 日：

• 開始編寫專案報告
• 開始編寫專案評估作業

專案完成階段

第 12 週 - 11/30 - 12/05：

• 確認並提交專案報告

第 13 週 - 3 月 12 日 - 12 月 10 日：

• 完成並提交專案評估

Google 文件季度結束後：

• 我希望持續參與 Bokeh 的開發工作，並繼續製作 Bokeh 的說明文件。
• 我打算繼續開發 OpenGraph/結構化資料中繼資料的 Sphinx 擴充功能。
• 我想將本人背景運用在新聞業和現有網路，宣傳 Bokeh 成為資料新聞業工具。例如，您可以將 Bokeh 與新聞讀者分享，或是提議在新聞場景中使用 Bokeh 的相關會議內容。

6. 關於我自己

我起初是記者，背景有電視、網路和廣播新聞。我在電視和數位新聞的編輯和記者，已有多年的寫作和編輯經驗。同時，我參與了多項專案來推動數位轉型和自動化。我撰寫了數份手冊，內容涵蓋數位工具和工作流程，以及數位新聞品牌的樣式指南和溝通策略。此外，我也訓練過團隊成員使用這些工具的相關訓練。

我一直很喜歡通訊和科技之間的交際。向我學習以 Python 編寫程式碼時，我向來開啟了一個全新的世界：例如，我用了資料分析和圖表來做資料新聞業等等。學習程式設計也讓我積極與軟體工程師合作，開發新聞編輯室工作流程的數位工具。

很可惜，我先前就讀的手冊和文件是不公開的。因此，我現在會將重點放在更深入地參與開放原始碼專案 (請參閱下方範例)。我任職於撰寫技術文件的技術內容，例如 Google 的開發人員說明文件樣式指南和 Microsoft 樣式指南。我經常使用 GitHub、Slack 和 Linux。我一直使用 Sphinx、Mypy 和 Sphinx autodoc 等工具撰寫論述文件、文件字串和類型提示。

我現在工作自由。根據我的時間表，在文件開發階段，我的時間表提供必要的彈性，可讓您每週約 25 小時處理 Bokeh 的說明文件。目前任職於太平洋時區，但很樂意配合團隊的時間表和需求。

7. 最近的開放原始碼說明文件範例

• PyZillow：PyZillow 是適用於房地產網站 Zillow.com API 的 Python 包裝函式。除了提供部分程式碼，並以程式碼維護人員的身分執行作業，我編寫了完整說明文件。我曾在敘事說明文件和單元參考資料中使用 Sphinx。我根據新增至程式碼的 docstring 內容，使用 Sphinx 擴充功能 autodoc 建立模組參照。

• PyPresseportal：PyPresseportal 是適用於 Presseportal.de 網站 API 的 Python 包裝函式，網站 presseportal.de 網站是德國最大的新聞稿和投資人關係發布宣導者之一。舉例來說，幾乎所有警察和消防部門都會使用這項服務來發布新聞稿。身為記者，使用 API 多年後，我決定開發 Python 介面，以便透過 Python 物件存取網站中豐富的資料資源。我編寫程式碼和完整的 Sphinx 型說明文件。