Fowel

Fowel 是什麼？

Fowel 是一款 GitHub App，會審核 pull request 中的文件變更。它會自動張貼內嵌評論與總結審核，協助在變更合併前捕捉文件問題，例如不正確或過時資訊、缺少脈絡、不清楚的表述，以及損壞的範例。

Fowel 的核心目的是在程式碼審核旁新增自動化文件品質檢查。它針對文件檔案（包含 Markdown 和 MDX）進行多項品質因素評估，讓開發者和審核者能在工作流程早期解決問題。

主要功能

• 針對每個 PR 的文件審核 GitHub App：Fowel 安裝至 GitHub 儲存庫，並在 pull request 包含文件變更時執行審核。
• 自動偵測文件檔案：當 PR 中修改 Markdown、MDX 及其他文件類型時，它會自動偵測，讓審核者無需手動選擇檢查項目。
• 內嵌評論加總結審核：Fowel 在 pull request 中張貼詳細內嵌回饋與整體審核，讓問題在審核期間一目了然。
• 跨多項品質因素的文件稽核：檢查內容準確性、開發者歷程/入門流程、結構與資訊架構、程式碼範例（包含可執行性與錯誤處理）、清晰度與風格，以及完整性。
• 支援自動與手動審核：產品包含自動化審核執行，以及手動觸發審核的功能。

如何使用 Fowel

1. 安裝 GitHub App：使用一鍵安裝流程將 Fowel 新增至您的儲存庫。網站說明無需設定檔、CI 變更或安裝腳本。
2. 開啟包含文件變更的 pull request：將文件更新推送到分支並開啟 PR。Fowel 會自動偵測文件檔案。
3. 在 PR 中檢視 Fowel 的回饋：檢視 Fowel 張貼的內嵌評論與總結。處理問題（例如過時陳述、缺少錯誤文件，或損壞程式碼範例），並視需要更新 PR。

使用情境

• 合併前捕捉過時程序：當團隊更新 API 文件或指南時，Fowel 可標記僅靠程式碼審核無法發現的矛盾與不正確程序。
• 改善「首次成功時間」入門流程：Fowel 評估文件的開發者歷程面向，確保使用者不會因缺少設定脈絡而中斷，順利完成首次 API 呼叫。
• 驗證參考文件品質：針對端點與 API 參考頁面，Fowel 檢查導覽、結構、命名、跨連結，以及文件完整性是否支援開發者查詢特定細節。
• 偵測損壞或誤導性程式碼範例：當範例過時或缺少必要錯誤處理時，Fowel 驗證可執行性與語法正確性，避免開發者複製/貼上失敗片段。
• 減少因缺少錯誤/脈絡文件導致的支援負擔：針對涉及參數、認證說明或錯誤回應的文件變更，Fowel 著重檢查資訊是否存在且足夠清晰，以避免「猜測」與重複提問。

常見問題

Fowel 只審核 Markdown 檔案嗎？
不是。頁面說明它會在 pull request 包含時自動偵測 Markdown、MDX 及其他文件。

結果顯示在哪裡？
Fowel 會在 pull request 上張貼內嵌評論與總結審核。

審核只能自動觸發，還是可手動？
兩者皆支援：產品包含自動審核與手動觸發。

Fowel 檢查文件的哪些項目？
它跨多項品質因素執行文件稽核，包含內容準確性、開發者歷程、結構與資訊架構、程式碼範例、清晰度與風格，以及完整性。

Fowel 會取代程式碼審核嗎？
網站將 Fowel 呈現為 pull request 工作流程中的額外文件品質檢查；它補充程式碼審核，專注程式碼審核者可能忽略的文件問題。

替代方案

• 內部文件審核流程（檢查清單或同儕審核）：團隊可依賴人工審核者使用品質檢查清單。相較 Fowel，這較不自動化，且通常較晚發現問題。
• 靜態文件 linting/linters：文件 lint 工具可強制格式或基本正確性規則。它們通常無法提供 Fowel 所述的多面向文件審核與脈絡內嵌審核。
• 內建驗證的 API 文件平台：協助產生 API 文件的工具可減少特定來源的文件漂移，但可能無法如 Fowel 所述般審核散文品質、入門流程、結構與範例可執行性。
• 一般拉取請求審核自動化：廣泛的 CI 或 PR 自動化可標記建置與測試故障，但並非專門針對文件準確性、清晰度與完整性量身打造。