Bokeh 專案

本頁面包含 Google 技術文件季度接受的技術寫作專案詳細資料。

專案摘要

開放原始碼組織：
散景效果
技術文件撰稿者：
vis_verborum (vis_verborum)
專案名稱：
建立、閱讀、分享：《最佳化 Bokeh》的說明文件
專案長度：
標準長度 (3 個月)

Project description

建立、閱讀、分享：改善 Bokeh 說明文件

1. 摘要

Bokeh 是一項非常強大的工具，可用 Python 建立互動式瀏覽器視覺化資料。它擁有龐大的使用者群 (每月下載 502,000 次 conda，下載 855,000 次 PyPi)，以及眾多貢獻者 (GitHub 上的 455 名貢獻者)。因此，Bokeh 的豐富說明文件自然而然地不斷成長。因此，在某些地方，資料不一致、難以存取且複雜。

Google 的說明文件季節提供了一個獨特的機會，可專注審查及修訂 Bokeh 說明文件的結構和內容，並確保說明文件和相關工具及工作流程能因應未來需求。

我曾使用 Python 和 Sphinx 編寫開放原始碼專案的程式碼和文件 (最近的專案是 PyZillow 和 PyPresseportal)。不過，我之所以能參與 Google 的「文件季」活動，是因為我有新聞工作背景：我曾在新聞編輯室工作超過 13 年，多年擔任總編輯，並致力於推動數位轉型。除了我的新聞職責外，我在設計及記錄新的數位工具和內容指南方面更負起責任，也開始訓練新聞編輯室員工的職責。

我最近從歐洲搬到美國，因此決定深入研究新方法，將我對溝通和程式設計的熱情結合起來。我發現技術寫作是結合我寫作和技術方面的技能和經驗的最佳方式。在這份提案中，我將說明如何利用 Google 的「文件季」來改善 Bokeh 的文件：讓建立和貢獻文件更方便，讓閱讀文件更直觀，以及讓分享文件中的資訊更容易。

2. 目前情況

Bokeh 的官方文件包含以下主要單元：

  • 說明文件：安裝指南、使用者指南、開發人員指南、發布說明
  • 相片庫和示範 (互動式範例及其原始碼)
  • 參考指南 (以 docstring 為基礎的說明文件)
  • 教學課程 (mybinder.org 代管的 Jupyter 筆記本完整收藏)
  • IDE 的說明字串和模型說明
  • 專案存放區中的範例和 README

此外，您也可以前往 Bokeh 支援論壇和 Stack Overflow 查看豐富的資訊。在這些論壇中，Bokeh 的開發人員會積極回答使用者的問題，而 Bokeh 的 Medium 網誌也提供相關資訊。

大部分說明文件網頁都是以 Sphinx 建立，使用數種標準和自訂 Sphinx 擴充功能。舉例來說，參考指南是使用「autodoc」和自訂的「bokeh_autodoc」等擴充功能，從 docstring 產生。由於自然成長的說明文件本質上會包含重複和不一致的內容，因此參考指南也包含重複和不一致的內容。

在分析現有文件時，我首先發現的是，文件撰寫缺乏明確的風格指南。Bokeh 開發人員指南提供一些基本操作說明。不過，本文件並未提供太多樣式相關指南，特別是與 docstring 以外的說明文件相關指南。因此，由於風格和結構問題，使用者 (尤其是新手) 更難存取文件中的資訊。

例如：

Bokeh 的說明文件到達網頁相當簡短，且未提供所有可用資源的資訊 (未提及大量的 docstring 和模型說明函式、支援論壇、示範或 Medium 網誌)。新使用者也更難開始使用 Bokeh。

3. 目標

為了讓十一週的文件開發階段發揮最大效益，我將著重於三個重點：

3.1. 改善文件建立作業

大多數的 Bokeh 說明文件都是由貢獻者撰寫，他們會在提交新功能和修復錯誤的拉取要求中，附上說明文件。雖然我會透過部分文件開發階段編輯及重構現有文件，但會強調建立及維護文件未來發展的工作流程，讓貢獻者能盡可能輕易維持高標準的文件品質。

我會透過兩種方式確保這項要求：

  • 我會建立一套實用且簡單的樣式指南，納入現有的開發人員指南。這些指南將說明文體、文法和結構。此外，我也會透過 Slack 等內部通訊管道，確保 Bokeh 的內容提供者瞭解樣式指南。我也會為團隊提供一對一訓練課程和問答活動。
  • 我會與核心團隊合作，找出最適合的技術文件品質控管工具組合，並將其加入 Bokeh 現有的 PR (pull request) 和 CI (持續整合) 工作流程中。視團隊的需求而定，這可能包括新增 pydocstyle、proselint 或 sphinxcontrib-spelling 等工具檢查 Bokeh 測試套件的拼字檢查、預先修訂設定或 GitHub 動作。我已在我自己的其中一項開放原始碼專案的 GitHub 動作中新增概念驗證。

3.2. 提昇文件閱讀能力

良好的說明文件旨在讓現有和潛在使用者輕鬆找到所需資訊，並盡可能有效運用這些資訊。

文字可用性和結構的關鍵因素在於文字的風格和結構：以清楚一致的方式撰寫說明文件，讓讀者快速瞭解資訊，而不會分心，且用多餘的語言。文件結構簡單明瞭，可以讓使用者輕鬆找到相關資訊。

我會著重於這兩個領域，並特別強調新使用者的可用性。包括全面檢視以「使用手冊」撰寫的敘事文件。此外，我也會改良說明文件到達網頁，以便更清楚地針對不同的目標對象設定問題，並確保每位使用者都能快速找到合適的資源。

如同改善上述文件的建立方式，我將著重於奠定未來改善的基礎，並持續為 Bokeh 的說明文件奠定高標準。

3.3. 改善文件共用功能

越來越多人針對 Bokeh 透過第三方平台展開討論。許多平台都會使用中繼資料 (例如 Facebook 的 OpenGraph)，加入連結的互動式預覽畫面。OpenGraph 可用於 Facebook、Twitter、LinkedIn、Slack 和 iMessage 等服務。Bokeh 的 Discourse 論壇也使用 OpenGraph 算繪連結預覽畫面。

為了使用這項技術，我會將中繼資料新增至 Bokeh 的 Sphinx 產生的網頁，如問題 #9792 所述。最有效率的方法是使用專屬的 Sphinx 擴充功能。幾天前，我們在 GitHub 上發布了第一個版本的 OpenGraph 資料 Sphinx 擴充功能。我會在文件開發階段使用一些功能，協助改善這個擴充功能，以便與 Bokeh 說明文件搭配使用。

我還建立了概念驗證，並成功在自己的開放原始碼專案 PyPresseportal 中使用。這個擴充功能會自動收集相關資訊，例如標題、說明、圖片和網址。接著，系統會將這些資訊以 OpenGraph 標記的形式插入 Sphinx 產生的 HTML 程式碼中。

開發這項擴充功能的下一步，是引入自訂指令，以便手動定義 OpenGraph 中繼資料 (類似 docutil 現有的「meta」指令)。自動產生的中繼資料只會在沒有手動輸入資料的情況下做為備用。

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

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

4. 交付項目

總結來說，以下是我期望在「文件季」中完成的成果：

  • 散景貢獻者的說明文件樣式指南
  • 修訂 PR 和 CI 工作流程，納入自動化文件品質驗證
  • 編輯及重新編排的使用者指南
  • 修訂版說明文件到達網頁
  • 說明文件網頁內含的 OpenGraph 中繼資料和正常運作的 Sphinx 擴充功能

此外，我會在個人網站/Medium 或 Bokeh 的 Medium 網誌上，記錄 Google 文件季的歷程，並將這些內容整理成「文件日誌」。這也是 Google 專案報表的依據。我會盡可能以 GitHub 問題和提取要求的形式，公開透明地進行所有工作。

5. 時間軸

發展尚未結束社群的階段：我目前已積極參與 Bokeh 的 GitHub 存放庫中的多次討論，也曾與 Bokeh 的 Google 文件季導師 Bryan Van de Ven 和 Pavithra Eswaramoorthy 聯絡。我會持續參與 Bokeh 相關討論，並透過建立及發布圖表，進一步熟悉 Bokeh。

社群凝結階段 (08/17 - 09/13)：

  • 認識核心團隊，調整專案計畫以與導師交流
  • 設定時間表和溝通管道，定期向導師回報進度並取得意見回饋
  • 在 Bokeh 的 Slack 上保持活躍，向所有感興趣的 Bokeh 貢獻者說明 Google 的「文件季」活動，以及文件開發階段的目標
  • 向 Bokeh 貢獻者收集意見回饋，進一步改善說明文件開發階段的計畫

文件開發階段

第 1 週 (9/14 至 9/20)：

  • 開始稽核及編輯論述說明文件
  • 開始起草樣式指南

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

  • 繼續改善樣式指南
  • 繼續編輯說明文件
  • 開始徹底改造說明文件到達網頁

第 3 週 (9/28 - 10/4)：

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

第 4 週 (10/5 至 10/11 日)：

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

第 5 週 (10/12 至 10/18)：

  • 在 Slack 上與 Bokeh 貢獻者進行問答，討論樣式指南、敘事說明文件的改善方式，以及 PR/CI 工作流程
  • 開始將現有的 OpenGraph 中繼資料概念驗證開發為可部署的 Sphinx 擴充功能
  • 根據與 Bokeh 貢獻者進行問答時的意見回饋，修訂樣式規範

第 6 週 10/19 - 10/25：

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

第 7 週 (10/26 至 11/01)：

  • 測試 Sphinx 擴充功能
  • 與 Bokeh 貢獻者在 Slack 上進行第二次問答
  • 根據第二次問答階段的意見回饋修訂成果

第 8 週，11/2 至 11/8：

  • 部署 Sphinx 擴充功能，並發布改善的說明文件和說明文件到達網頁

第 9 週 (11 月 9 日 - 11 月 15 日)：

  • 在 PR 和 CI 工作流程中部署文件品質管制工具
  • 更新及發布開發人員指南，納入樣式規範，以及 PR 和 CI 工作流程新增項目

第 10 週 (11/16 - 11/22)：

  • 完成剩餘工作

第 11 週 (11/23 至 11/29)：

  • 開始撰寫專案報告
  • 開始撰寫專案評估

專案完成階段

第 12 週，11/30 至 12/5：

  • 完成並提交專案報告

第 13 週，12/3 至 12/10：

  • 完成並提交專案評估

Google 的「Google 文件季節」活動結束後：

  • 我希望持續參與 Bokeh 的開發工作，並繼續撰寫 Bokeh 的說明文件。
  • 我打算繼續開發 OpenGraph/結構化資料中繼資料的 Sphinx 擴充功能，
  • 我希望將我的新聞背景和現有網路，推廣 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 為基礎的說明文件。