概述
這很重要,因為文件常常落後於快速發展的產品。人工智慧可以加快起草和更新速度,但它也可以發明聽起來令人信服的參數或行為。
深入探討
技術寫作長期以來一直是部分自動化的。參考文件通常是使用 Swagger UI、Redoc 和 Sphinx autodoc 等工具根據程式碼註解或 API 規格產生的。生成式人工智能添加的是散文:概念解释、教程、示例、发行说明以及根据产品需求文档或工程说明编写的初稿。許多團隊都在文件即程式碼模型中工作。文档在 Git 中以 Markdown 或 reStructuredText 形式存在,更改通过拉取请求进行,持续集成使用静态站点生成器(例如 Docusaurus、MkDocs 或 Sphinx)构建站点。這種設置非常適合人工智慧。草稿作為可審查的變更到達,每次提交都會執行自動檢查,並且文件更新可以與導致它們的程式碼變更相關聯。為了風格的一致性,確定性工具和人工智慧相輔相成。像 Vale 这样的 linter 会强制执行风格指南中的规则,例如 Google 的开发人员文档风格指南或 Microsoft 写作风格指南,并且每次都会给出相同的结果。人工智慧更擅長提出更清晰的措辭,但它的可預測性較差。主要風險是信心不準確。模型可以發明一個端點、一個預設值或一個看起來合理的命令列標誌。它還可以描述產品在訓練資料中的行為方式,而不是現在的行為方式。每個產生的程式碼範例和參數都需要針對真實系統進行檢查。一個常見的誤解是人工智慧讓技術作家變得不必要。這項工作的困難在於了解什麼是真實的、確定使用者需要什麼以及組織資訊以便他們能夠找到它。像 Diátaxis 這樣的框架將教程、操作指南、參考和解釋分開,反映了這種結構性工作。角色正在轉向資訊架構、驗證、內容策略和人工智慧讀者的寫作。例如,2024 年的 llms.txt 提案建議使用一個文件將語言模型指向網站的關鍵文件。
現實世界的實施
一位作者為 AI 提供了 OpenAPI 規格和團隊的頁面模板,並要求提供概念概述和入門演練。然後,他們在測試環境中運行每個程式碼範例。
文件儲存庫以持續整合方式運行 Vale 散文 linter,以標記禁用術語和被動語態。人工智慧助理建議重寫標記的句子,然後作者接受或拒絕每一個句子。
當工程師的拉取請求重新命名配置標誌時,AI 步驟會起草匹配的文檔變更。作者在合併之前對其進行了審查。
作者將冗長的故障排除頁面重組為帶有描述性標題的獨立部分。這有助於人類讀者和人工智慧助理從文件中提取段落。
科技作家的人工智慧未來
在人工智慧起草和人類批准的情況下,文件可能會隨著程式碼變更而更持續地產生和更新。更多读者将通过人工智能助手而不是浏览来获取文档,这提高了准确、结构良好的内容的价值,这些内容在分段阅读时会发挥作用。 llms.txt 等約定仍是提案,其採用尚不確定。對純粹起草的需求可能會下降,而對能夠檢查技術準確性、設計資訊架構和自身文件品質的人員的需求可能會保持穩定或成長。就業市場將如何分化仍不清楚。
付諸實踐
為什麼這很重要
- 配裝選擇. 應用級設計決定了人工智慧是否能改善實際結果。
- 團隊與工作流程. 良好的工作流程整合可以創造使用者值得信賴的生產力效益。
- 風險與安全. 範圍明確的用例可以減少變更疲勞和實施風險。
留意
- 將損壞的流程自動化可能會加劇現有問題。
- 團隊可能會過度自動化並消除所需的人工判斷。
- 如果不持續評估輸出,品質可能會出現偏差。
後續步驟
- 繪製目前工作流程並確定摩擦最大的步驟。
- 在完全自動化之前定義人工檢查點。
- 對使用者進行提示、升級路徑和品質標準的訓練。
- 追蹤任務級結果以確認持續價值。
不斷探索
常見問題
什麼是技術作家的人工智慧?
技术作家的人工智能意味着使用语言模型根据规范和代码起草文档,保持风格一致,并支持文档即代码工作流程,而作者则对准确性和结构负责。這很重要,因為文件常常落後於快速發展的產品。人工智慧可以加快起草和更新速度,但它也可以發明聽起來令人信服的參數或行為。
Vale linter 在文件即程式碼工作流程中做什麼?
Vale 是一種散文 linter,可以確定性地強制執行樣式規則。人工智慧對於更清晰措辭的建議不太可預測。
什麼最能描述文檔即程式碼?
在文件即程式碼中,文件以 Markdown 或類似形式存在於 Git 中,透過拉取請求,並由 CI 使用靜態網站產生器建構。
Diátaxis 框架區分哪四種內容類型?
Diátaxis 將文件分為教學課程、操作指南、參考和解釋,每種都滿足不同的使用者需求。
為什麼人工智慧產生的程式碼範例應該作為測試運行?
信心不準確是主要風險。可執行樣本使發明的參數導致建置失敗。
llms.txt 提案是什麼?
llms.txt 於 2024 年提出,是一種將語言模型引導至重要文件的約定。它的採用仍不確定。