产品知识库的类文档代码方法

听说过代码之类的文档吗？你可能有。去年，它的受欢迎程度激增，尤其是在纪录片界本身。

SaaS 企业正在意识到像对待代码一样对待文档的想法，尽管这种方法并不是全新的。

这是开源社区中文档和代码的传统方式，其中文档通常与源代码一起存在（当它存在时！）。这个想法正在慢慢渗透到商业世界，并且对于 SaaS 公司尤其有效。

有一些软件工程实践可以真正帮助您处理文档。

你如何对待源代码

版本控制

持续交付模式

入住政策

审核流程（测试）

将其投入生产（公开）

将文档视为代码意味着将文档与源代码保存在同一系统（通常类似GitHub ）中，并采用相同的开发流程。

这意味着整个团队在文档方面进行协作，而不是在孤岛中进行技术写作和工程。

软件开发和技术写作使用相同的流程和开发方法——将文档视为源代码。

代码等文档的背景

在软件行业，人们非常关注代码——为什么不呢！它是我们产品的核心部分。良好、干净、注释良好、可工作的代码是绝对重要的交付成果。

同时，文档也至关重要。问题最终陷入了这个非此即彼的陷阱，我们觉得我们必须在文档或代码之间做出选择。现实情况是，文档应该被视为与代码相同但不同，这是“像代码一样的文档”方法的基础。

在敏捷方法中，文档通常被视为对代码的诅咒——被视为减慢生产速度，并且是火箭推进的发射之旅中不必要的压舱石。

文档应该是必要的并且与软件团队相关，而不是像传统的瀑布式开发方法那样进行勾选练习。为您的团队生成正确文档的最佳方式可能是像代码这样的文档，可随您的产品扩展的知识库软件。

为什么需要代码之类的文档？

Ann Gentle 出版了她的著名书籍Docs Like Code以及她的同名网站后，这种方法更加普及。她的书的口号是：写作。审查。测试。合并。建造。部署。重复。这反映了文档制作如何与软件开发过程保持一致。

她探讨了高科技中人工知识层次结构的概念——代码天生优于其他形式的知识或技能。这导致人们对非代码的可交付成果持轻蔑态度，也被视为“浪费时间”。

随着技术写作的遗产赶上现代软件开发实践，这可能更有意义。

过去，技术写作团队使用大型、笨重的发布系统来管理文档，这些系统具有昂贵的许可证，并且用户体验有限。代码开发后整理文档确实花费了很多时间。

可以理解的是，人们对代码之类的文档有很大的兴趣——尤其是在预算下降和加大生产压力的情况下。

优点

使用类似代码的文档方法有很多优点。以下是进行转变的一些主要原因：

它有助于使文档与源代码保持一致，并且最终用户可以看到文档的最新版本

这意味着您可以与主题专家密切合作，他们最适合为文档提供最初的灵感。

您可以使用版本控制来帮助管理编辑和协作过程，从而更轻松地恢复到早期版本

文档更加重要，因为您可以在交付文档之前禁用合并

缺点

像代码这样的文档并不适合所有人。在做出任何仓促决定之前，请务必牢记这种方法的局限性。

它可能会排斥非技术导向的团队成员，并且工具的学习曲线很陡。新技术编写人员可能需要接受培训才能跟上进度，从而增加了团队实现最大生产力的成本。

文档并不完全像代码，如果你太努力，你可能会冒着试图将方钉强行插入圆孔的风险。

可能无法允许技术作家使用与工程师相同的工具和系统。

文化变革是困难的。如果您的团队通常不这样做，您可能会遇到一些内部阻力。

如何让它发挥作用？

与敏捷方法论密切相关，代码之类的文档是现代开发团队协作生成文档和代码的新兴方式。

为了防止工程师将文档视为浪费时间，请将文档与代码放在同一级别。要求您的工程师在合并代码之前创建必要的文档。

如果您的开发人员正在制作文档，请立即停止。开发人员需要做他们得到报酬的事情：编写代码和开发软件。您需要聘请专业的技术作家来负责您的文档。

从一开始就让您的技术作家与您的开发人员一起参与每个软件项目。避免在开发结束时疯狂的 48 小时忙于将文档放在一起，以便您的软件可以按时交付。

如果您的技术作家在适应开发团队使用的版本控制平台方面遇到困难，您可以考虑使用知识库软件。

它将为您节省培训技术作家的麻烦和资源。这通常会让他们更容易地完成工作。然而，这意味着开发人员和技术编写人员必须相互协调以适应他们的节奏。

整个方法必须由高级管理层自上而下进行，以便整个团队都能参与进来。

简单直观的知识库软件可满足您的业务需求

最后的评论

没有单一正确的方法来部署代码等文档。这取决于每个团队和公司如何让它发挥作用。

许多团队已经在使用类似代码的文档方法，并且它将会变得更加流行。甚至英国政府的数字服务部门也采用类似代码的文档方式来编写技术文档。

为了成功做到这一点，您必须将文档与现有的工程流程集成——同时记住需要定期更新文档，而不必与软件开发周期保持一致。

技术作者需要更正缺少的逗号，而且他们现在就需要更正。

另请阅读：使用示例创建 API 文档的终极指南

对于代码之类的文档，问问自己：

谁负责运送文档？

我们需要的最重要的文件是什么？

我们想要生成什么文档？

我们的文档会是什么样子？

我们什么时候需要它？

谁可以为文档做出贡献？

我们将如何处理版本控制？

找到这些问题的答案，然后将您的文档作为代码策略启动。

从这往哪儿走？

以下是与该主题相关的全面解释视频，供您进一步研究：

有关转变文档流程的完整视频

到目前为止，您应该清楚地了解代码方法等文档的含义以及它如何为您的产品带来好处。

无论处于哪个开发阶段，您都应该以与编写代码和添加新功能相同的速度来编写文档。

编写文档不再需要对作者进行大量培训。事实上，您可以利用知识管理软件来使您的文档与您的代码及其不同版本保持同步。

如果您认为我们可能遗漏了某些内容，或者您想就此分享您的想法，请在下面的评论部分告诉我们。

Baklib是 SaaS 团队的文档解决方案。立即享受免费试用。