如何为开发人员自动化文档工作流程

要充分利用本教程，您应该熟悉：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。

结论

在一个越来越偏远的世界中，优先考虑良好的文档和良好的文档工作流程很重要。 您首先必须通过创建样式指南来定义什么是“好”。 一旦您弄清楚了文档的规则，就该自动化了。

文档应该像你的代码库一样对待：一个活生生的工作体，它不断地被迭代，并且比你上次更新它时变得更好。