如何為開發人員自動化文檔工作流程

要充分利用本教程，您應該熟悉：Git、GitHub 和 Linux 以及命令行。

為什麼要關心高質量的文檔？

許多團隊都在努力編寫文檔。 當你去檢查一個框架時，文檔通常會過時或不清楚。 當團隊成員嘗試添加功能時，這可能會導致內部挫敗感，但由於文檔不足，他們不了解當前功能的工作原理。 這可能會導致工作效率低下。

糟糕的文檔也會影響良好的客戶體驗。 根據Ask Your Developer的作者和 Twilio 的創始人 Jeff Lawson 的說法，如果您將 API 作為產品銷售，文檔是技術利益相關者的終極廣告。 IBM 對文檔的重要性進行了一項研究，90% 的受訪者承認他們根據產品文檔的質量做出購買決定。

編寫好的文檔對於開發人員和客戶體驗很重要。

如果文檔如此重要，那麼為什麼工程團隊會降低它的優先級？

編寫文檔可以讓開發人員脫離“流程”。 文檔通常位於主代碼庫之外，查找和更新很麻煩。 將其放入 Excel 電子表格或專有 CMS 並不少見。

自動化文檔和改進文檔工作流程解決了這個問題。

從高級別自動化文檔

自動化文檔是什麼意思？ 這意味著採用通用的軟件開發實踐。 當您自動化文檔時，您是：

• 用 Markdown 編寫文檔；
• 使用持續集成和持續部署 (CI/CD) 管道來運行諸如糾正錯誤和部署更新等任務（在本教程中，我們將重點介紹 GitHub 操作）；
• 實施像 Vale 這樣的工具來執行風格指南並糾正常見的語法錯誤。

風格指南

在使用 Vale 和 GitHub Actions 等工具來自動化樣式指南之前，讓我們花點時間來定義究竟什麼是樣式指南。

您知道在編寫文檔時感覺有些不對勁嗎？ 您的解釋與文檔的其餘部分不相符，但您無法完全描述它們為什麼錯了。 文章解釋了這個概念，但似乎並不合適。

當你有這種感覺時，你的聲音和語氣可能會變差。 即使您正在開發已由 QA、工程和產品團隊編輯的文檔，優化聲音和語氣也是一種使寫作聽起來有凝聚力的方法。 下面是來自城市公交應用程序 TAPP 的示例樣式指南，摘自 Torrey Podmajersky 的《為用戶體驗戰略寫作》一書。

TAPP 是一個交通應用程序（用於公共汽車和火車）。 表格的標題表明了 TAPP 作為一家公司的價值觀，即高效、值得信賴且易於使用。 表格左側列出了風格指南涵蓋的不同部分：概念、詞彙、詳細程度、語法和標點符號。

這些共同構成了風格指南。 標題介紹了這些值，表格的左側顯示了您在任何書面材料中都會找到的不同組成部分：詞彙、語法和標點符號。 這本風格指南的美妙之處在於，工程師和文案人員將清楚地知道使用什麼大寫字母以及使用哪個標點符號來提升 Tapp 的品牌形象。

技術寫作風格指南

並非所有風格指南都以表格形式出現。 微軟有一個完整的網站作為綜合指南，涵蓋從首字母縮略詞到無偏見通信再到聊天機器人的所有內容。 微軟當然不是唯一擁有風格指南的公司。 谷歌也有一個。

風格指南的問題

對於認真對待文檔的公司來說，風格指南是一個很好的起點。 它們解決了開發人員可能對如何準確撰寫他們推出的主要功能的許多困惑。

風格指南的問題在於它們給寫作過程增加了摩擦。 包括我在內的許多作家，每次遇到問題時都不會停止寫作並查看風格指南。 有時，樣式指南很麻煩且難以參考——例如，Microsoft 樣式指南長達一千多頁！

用於文檔的 Linters 和 CI/CD

如果您是程序員，那麼您可能熟悉 linter。 Linter 是在團隊中強制執行編碼標準的理想方式。 文檔也是如此。 創建 linter 時，您正在為文檔設置質量基準。 在本教程中，我們將使用 Vale linter。

在 linter 旁邊使用某種文檔自動化是很常見的。 當我們在這種情況下說自動化時，我們指的是持續集成和持續部署 (CI/CD) 工作流程。 CI 使文檔的構建和測試自動化。 CD 自動發布代碼。

您可以使用許多不同類型的應用程序來實現 CI/CD 工作流。 在本教程中，我們將使用 GitHub Actions 來運行我們的文檔 linter。 GitHub Actions 直接在 GitHub 存儲庫中運行 CI，因此無需使用第三方應用程序，例如 CircleCI 或 Travis。

最後，GitHub Actions 是事件驅動的，這意味著它們會在發生某些事情時觸發，例如當有人編寫拉取請求或問題時。 在我們的示例中，當有人將更改推送到其主分支時，將發生 GitHub 操作。

GitHub 操作

首先，創建一個 GitHub 存儲庫。 然後，在本地創建一個文件夾並cd進入其中。

 mkdir automated-docs cd automated-docs

進入文件夾後，為 Git 初始化目錄。

 git init

初始化存儲庫後，繼續為您的文件夾創建工作流目錄。

 mkdir .github/ && cd .github/ && mkdir workflows/ && cd workflows/

工作流是我們存儲所有 GitHub 操作的地方。 創建workflows文件夾後，創建一個新的工作流。 我們將把這個工作流程命名為vale.yml 。

 touch vale.yml

Vale.yml是一個 YAML 文件。 在此工作流文件中，我們將包含操作和作業。

現在，在你最喜歡的文本編輯器中打開vale.yml 。

 nano vale.yml

將以下內容複製並粘貼到vale.yml中，讓我們回顧一下上下文和語法。

 # This is a basic workflow to help you get started with Actions name: CI # Controls when the workflow will run on: # Triggers the workflow on push or pull request events but only for the main branch push: branches: [ main ] pull_request: branches: [ main ] # Allows you to run this workflow manually from the Actions tab workflow_dispatch: # A workflow run is made up of one or more jobs that can run sequentially or in parallel jobs: # This workflow contains a single job called "build" build: # The type of runner that the job will run on runs-on: ubuntu-latest # Steps represent a sequence of tasks that will be executed as part of the job steps: # Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it - uses: actions/checkout@v2 # Runs a single command using the runners shell - name: Run a one-line script run: echo Hello, world! # Runs a set of commands using the runners shell - name: Run a multi-line script run: | echo Add other actions to build, echo test, and deploy your project. env: GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}}

• name
  這是名稱，或者我們稱之為工作流程的名稱。 它是一個字符串。
• on
  這控制工作流程和触發器。
• jobs
  這是我們設置和控制我們的行動的地方。 我們選擇我們的操作將運行的環境——通常使用 Ubuntu 是一個不錯的選擇。 這就是我們將添加我們的操作的地方。

GitHub 有關於所有其他工作流語法和變量的指南，以防你好奇。

在本節中，我們有：

• 了解了 GitHub 操作是什麼，
• 創建了我們的第一個 GitHub 工作流程，
• 確定了 GitHub 工作流 YAML 文件中最重要的部分。

接下來，我們將自定義我們的 GitHub 工作流程以使用 Vale。

在 GitHub Actions 文件中設置 Vale

一旦我們複製了基本工作流文件，就可以對其進行自定義，以便我們可以開始使用 Vale 操作。 首先要做的是將 YAML 文件的名稱更改為Docs-Linting 。

 # This is a basic workflow to help you get started with Actions. name: Docs-Linting

接下來，一旦有人將他們的更改推送到 GitHub 上的主分支，我們想運行 Vale 測試。 我們不希望在有人創建拉取請求時運行測試，因此我們將刪除 YAML 文件的該部分。

 on: # Triggers the workflow on push or pull request events but only for the main branch push: branches: [ main ]

jobs部分是工作流文件的主要部分，它負責運行 GitHub 操作。

 jobs: build: runs-on: ubuntu-latest steps: - name: Checkout uses: actions/checkout@master

這些操作將在最新版本的 Ubuntu 上運行。 Checkout操作簽出存儲庫，以便 GitHub 工作流訪問它。

現在是時候向我們的 GitHub 工作流程添加 Vale 操作了。

 - name: Vale uses: errata-ai/[email protected] with: debug: true styles: | https://github.com/errata-ai/write-good/releases/latest/download/write-good.zip https://github.com/errata-ai/Microsoft/releases/latest/download/Microsoft.zip env: GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}}

我們將動作命名為Vale 。 uses變量顯示了我們將要實現的 Vale 版本——理想情況下，我們應該使用最新版本。 在with變量中，我們將debug設置為true 。

styles部分為我們提供了向 Vale 添加樣式指南的選項。 在此示例中，我們將使用write-good和 Microsoft 的官方樣式指南。 請記住，我們也可以使用其他樣式指南。

這個 GitHub 操作的最後一部分是env 。 為了運行這個 GitHub 操作，我們需要包含一個秘密令牌。

結果應該是這樣的：

 # This is a basic workflow to help you get started with Actions. name: Docs-Linting # Controls when the action will run. on: # Triggers the workflow on push or pull request events but only for the main branch push: branches: [ main ] # Allows you to run this workflow manually from the Actions tab workflow_dispatch: jobs: prose: runs-on: ubuntu-latest steps: - name: Checkout uses: actions/checkout@master - name: Vale uses: errata-ai/[email protected] with: debug: true styles: | https://github.com/errata-ai/write-good/releases/latest/download/write-good.zip https://github.com/errata-ai/Microsoft/releases/latest/download/Microsoft.zip env: GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}}

完成更改後，保存文件，提交到 Git，然後將更改推送到 GitHub。

 git add .github/workflows/vale.yml git commit -m "Added github repo to project" git push -u origin main

回顧一下，在本節中，我們有：

• 當我們將新代碼推送到main分支時觸發動作發生；
• 添加了 Vale 操作，將debug設置為true並識別樣式指南；
• 添加了一個 GitHub 令牌；
• 提交更改並推送到 GitHub。

在下一節中，我們將創建一個 Vale 配置文件。

設置 Vale 配置文件

轉到項目目錄的根目錄，然後touch .vale.ini 。 在文本編輯器中打開.vale.ini 。 將以下內容複製並粘貼到.vale.ini ：

 StylesPath = .github/styles MinAlertLevel = warning [formats] Markdown = markdown [*.md] BasedOnStyles = write-good, Microsoft

• StylesPath = .github/styles
StylesPath給出了 Vale 樣式的路徑。
• MinAlertLevel = warning
  最低警報級別顯示警報的嚴重程度。 選項是suggestion 、 warning和error 。
• [formats]
Markdown = markdown設置格式為 Markdown。
• [*.md]
  配置BasedOnStyles = write-good, Microsoft將對所有以.md結尾的 Markdown 文件運行 write-good 和微軟風格指南。

這種設置是最低限度的。 如果您有興趣了解有關配置 Vale 的更多信息，請參閱文檔。

完成更改後，保存文件，然後提交並推送到 GitHub。

 git add .vale.ini git commit -m "Added Vale config file" git push -u origin main

在這一部分中，我們學習了 Vale 配置文件的內部結構。 現在是創建示例文檔的時候了。

創建文檔並觸發 Vale GitHub 操作

現在是時候看看 Vale 和 GitHub Actions 的實際應用了！ 我們將創建一個 Markdown 文件並用文本填充它。 我們將從 DeLorean Ipsum 獲得我們的文本。

轉到項目的根目錄，然後touch getting-started.md 。 創建getting-started文件後，轉到 DeLorean Ipsum 並為您的文檔創建一些虛擬文本。 然後，返回到您的文本編輯器並將文本粘貼到getting-started-md中。

 # Getting Started Guide I can't play. It's my dad. They're late. My experiment worked. They're all exactly twenty-five minutes slow. Marty, this may seem a little foreward, but I was wondering if you would ask me to the Enchantment Under The Sea Dance on Saturday. Well, they're your parents, you must know them. What are their common interests, what do they like to do together? Okay. Are you okay? Whoa, wait, Doc. What, well you mean like a date? I don't wanna see you in here again. No, Biff, you leave her alone. Jesus, George, it's a wonder I was ever born. Hey, hey, keep rolling, keep rolling there. No, no, no, no, this sucker's electrical. But I need a nuclear reaction to generate the one point twenty-one gigawatts of electricity that I need. I swiped it from the old lady's liquor cabinet. You know Marty, you look so familiar, do I know your mother?

保存文件，提交，然後推送到 GitHub。

 git add getting-started.md git commit -m "first draft" git push -u origin main

推送更改後，轉到存儲庫所在的 GitHub。 轉到“ Actions ”選項卡。

您將在左側看到所有工作流程。 我們只有一個，名為Docs-Linting ，與我們放在vale.yml文件中的名稱相同。

當我們將文檔推送到 GitHub 時，我們將觸發該操作。

如果動作運行沒有任何問題，我們將得到一個綠色的複選標記。

單擊“添加的文檔”以獲取完整報告。

你會看到我們收到了 11 個警告。 讓我們來處理“weasel word”警告。 返回文本編輯器，打開getting-started.md並刪除“exactly”一詞。

 # Getting Started Guide I can't play. It's my dad. They're late. My experiment worked. They're all twenty-five minutes slow. Marty, this may seem a little foreward, but I was wondering if you would ask me to the Enchantment Under The Sea Dance on Saturday. Well, they're your parents, you must know them. What are their common interests, what do they like to do together? Okay. Are you okay? Whoa, wait, Doc. What, well you mean like a date? I don't wanna see you in here again. No, Biff, you leave her alone. Jesus, George, it's a wonder I was ever born. Hey, hey, keep rolling, keep rolling there. No, no, no, no, this sucker's electrical. But I need a nuclear reaction to generate the one point twenty-one gigawatts of electricity that I need. I swiped it from the old lady's liquor cabinet. You know Marty, you look so familiar, do I know your mother?

保存更改，將其提交到 Git，然後將文件的新版本推送到 GitHub。 它應該觸發 GitHub 操作。

如果我們點擊“Deleted the weasel word”，我們會看到我們現在只有 10 個警告，並且“weasel word”警告消失了。 萬歲！

我們已經完成了，我們已經覆蓋了很多領域。 在本節中，我們有：

• 向我們的 Vale GitHub Actions 存儲庫添加了文檔，
• 觸發 Vale GitHub 行動，
• 更正了 Vale 產生的錯誤並將更改推送回 GitHub。

結論

在一個越來越偏遠的世界中，優先考慮良好的文檔和良好的文檔工作流程很重要。 您首先必須通過創建樣式指南來定義什麼是“好”。 一旦您弄清楚了文檔的規則，就該自動化了。

文檔應該像你的代碼庫一樣對待：一個活生生的工作體，它不斷地被迭代，並且比你上次更新它時變得更好。