像开发代码一样编写文档

不想让文档成为事后才考虑的事情?尝试一种新方法。
5 位读者喜欢这篇文章。
Woman programming

WOCinTech Chat。由 Opensource.com 修改。CC BY-SA 4.0

许多工程师和工匠对他们的工具非常讲究。为了做好一项工作,您需要最好的工具以及使用它们的技能。当应用于其他类型的数字创作时,软件开发中最好的工具可能非常强大。“文档即代码”方法就是一个很好的例子。“文档即代码”意味着使用与开发代码相同的工具和工作流程来编写文档。“文档即代码”的支持者报告说,这种方法可以产生更好的文档,同时减轻编写文档人员的工作量。

文本格式和源代码控制

从更传统的文档平台转向“文档即代码”方法时,最显着的变化是内容存储在基于文本的标记格式中。这种改变使得所有用于基于文本材料的工具都可用于生成文档。无论您选择 DocBookMarkdown 还是另一种标记语言,从仅使用一种工具到使用标准格式和各种工具的过渡都是一个巨大的变化。

找到支持您的工作流程的工具非常重要。许多开发人员在处理“文档即代码”项目时使用他们的 编码编辑器。由于他们已经是该工具的高级用户,因此它对他们来说效果很好。为团队中的其他专业人员(例如技术作家、编辑、信息架构师和文档产品负责人)找到合适的工具可能需要付出更多努力。以下是一些值得考虑的选项:

  • 众多优秀的 Markdown 编辑器之一
  • 具有良好预览工具的编码编辑器,这使得它们对非编码人员也很友好
  • 流行的 Git 托管服务的 Web 界面,特别是对于偶尔的贡献者

一旦内容安全地采用标记格式,项目就可以使用源代码控制,例如 Git,这是一个开源工具,其功能比大多数文档平台所能声称的要多得多:

  • 清晰详细的版本历史,记录了谁在何时更改了什么。如果您有良好的提交消息文化,您甚至可以了解更改的原因。

  • 轻松的并行更改流程。在 Git 分支中工作意味着每个人都可以进行他们想要的所有更改,并在最后将它们合并。

  • 高级的协作和审查工具。所有源代码控制平台都旨在详细审查每个更改,并进行尽可能多的讨论,直到每个人都确信更改可以进行。

  • 自动化质量检查,例如拼写检查和链接检查。这节省了时间,并捕获了可能被遗漏的错误。

源代码控制有很多好处。请记住,如果您是源代码控制的新手,它有一个学习曲线。有一些优秀的 学习资源面向作家的文章 可以提供帮助。您也可以让您好奇的文档编写者找到适合他们的学习材料,而不是要求您的工程师教他们。(问问我是如何学会的——当然是通过艰难的方式!)

拉取请求和审查周期

所有源代码控制平台都围绕拉取请求(有时也称为合并请求)的概念而设计。某人或某个团队将一组更改放在一起,然后请求将更改拉取到主项目中。在许多方面,一次处理多个更改在文档中比在代码中更容易。在文档中在一个地方更改一篇文章的副作用比更改代码并发现还有其他几个部分依赖于它时要少。

最强大的协作工具是 diff,它可以以易于理解的方式显示新旧版本之间的差异。有许多版本的工具可用于使比较视图更易于查看:并排、内联,甚至以渲染的 markdown 而不仅仅是文本形式。每个团队成员都可以使用最适合他们的工具。例如,Web 视图通常用于查看小的更改,但对于更大的更改,我希望使用 vimdiffMeld 在本地查看它。

审查意见可以添加到整个更改或建议更改中的单行。一些项目采用最大行长度(称为硬换行),或在新行上开始每个句子,以便更轻松地将注释附加到文本块的特定部分。可以添加进一步的更改和注释,直到审查过程完成并且更改被接受。由于拉取请求显示在项目的存储库中的队列中,因此这是一个显示正在进行的工作以及需要审查关注的好方法。这些工具使审阅者可以轻松地添加他们的想法。特别是,如果您与技术受众合作,则通过他们每天使用的工具更容易获得这些人的评论。

持续集成和部署

以纯文本形式提供文档的源代码有很多好处,例如可以轻松找到每个需要更改的内容,并使用现有工具(例如 wcgreptree)来处理可能很大的文档集。当您将此与源代码控制平台结合使用时,甚至可以使用更多现有工具,并且它们都是开源的。

一个大的工作流程改进是能够实现持续部署。这仅仅意味着当拉取请求合并到主项目中时,该项目会立即自动部署。如果更改足够好以被项目接受,那么它也足够好以在文档站点上上线,从而帮助您的读者。通常,持续部署是使用单独的自动化服务器(例如 Jenkins)或 Git Hooks 设置的。无论哪种方式,基于文本的标记都与“文档即代码”平台(通常是静态站点生成器,例如 HugoSphinx)结合使用以生成文档网站,然后将其部署。

相同的自动化可以在部署之前使用,以便在拉取请求合并之前向其添加一些出色的检查。在编码项目中,通常运行代码 linter、测试和机器可以自行完成的其他质量检查。文档项目可以获得相同的待遇,使用像 Vale 这样的工具来进行散文 linting 并检查正确的标题样式、拼写等。在此处添加其他工具也很有用,例如链接检查器,以确保所有链接都指向有效的位置。

文档工作流程的代码工具

工程师们熟知和喜爱的工具是非常好的工具,但它们也适用于各种其他项目。对于文档,它们贡献了宝贵的效率,特别是当您需要您的文档以与您的开发团队相同的速度移动时。此处讨论的所有工具都是开源的,因此您可以亲自试用它们,为庞大的全球团队部署它们,或介于两者之间的任何操作。愿您的文档流程像任何代码流程一样顺畅。

User profile image.
Lorna 居住在英国约克郡;她是一位精通多种语言的程序员,也是一位已出版的作家和经验丰富的会议演讲者。她以其写作和演讲活动向世界各地的听众介绍她在各种主题上的技术专长,始终以非常实用的角度呈现。

4 条评论

作为一名快乐的系统管理员,我两年多前就开始采用这种方法。我使用 asciidoctor 作为标记语言、git 服务器以及我仍在开发的应用程序来分析所有文档、提取属性并生成一个美观但简单的静态网站,其中包含所有文档。

可惜的是,很少有人使用这种方法。他们更喜欢创建 Word 文档。这很遗憾。

感谢这篇文章。

有趣的文章。我有一个后续问题。文档中包含一些图形或视频表示形式怎么办?您将如何使用源代码控制系统将它们传输到文档中?您会将它们保存在哪里?将二进制文件保存在 git 存储库中不是一个好主意。

作为一名内容系统管理员,我已经使用这种策略两年多了。为了分析所有论文、提取属性并创建一个有吸引力但直接的静态网站,其中包含所有文档,我使用 asciidoctor 作为标记语言、git 服务器以及我仍在创建的应用程序。后室

Creative Commons License本作品根据 Creative Commons Attribution-Share Alike 4.0 International License 获得许可。
© . All rights reserved.