目录
你是不是经常听到客户这样说，“团队很棒，但美中不足的是项目没有文档”，或者“这是我们团队需要的框架，但文档已经过时”。
为什么这个问题如此普遍？为什么文档总是过时？可能以下三个原因：
-
没有与编写文档关联的职业奖励。
-
文档的编写没有衡量产出的标准，许多开发人员不愿意为没有衡量标准的项目付出努力。
-
文档很难维护。
没有与改进技术文件关联的职业奖励
编写文档会阻碍开发人员的晋升。
对于开发人员来说，写新功能一定会有回报，尤其在职业生涯的早期，写的代码越多越好，前提是不能制造太多技术负债或搞坏太多服务器。
假如你在从事软件开发职业的前三年里写文档，会被认为是不务正业。大家对工作岗位有潜在的等级划分，有些工作属于比较有含金量的工作，而有的工作只是打酱油的杂活。对于工程部门来说，编写内部框架和工具是最重要的，QA、客户服务以及文档编辑等工作岗位是这个金字塔的底层。虽然不同公司之间有差异，但许多公司的工程部门确实是这样运作的。
这种等级划分非常普遍，甚至都有专门的名字——“胶水”。这个名字起源于 “胶水代码”。胶水代码的功能是连接代码库中的两个不同部分，起到辅助作用，不是主角。在工程团队中成为“胶水”意味着你在做很多支持性的工作，但这些工作不能给你的职位带来晋升。优秀的文档可以让公司获利，但却不能促进开发人员晋升。
优秀的文档可以转化客户，让销售部门从中获利，但不能促进开发人员的晋升。优秀的文档能减少提交的票据数量，让 QA 部门从中受益，但对工程师一点好处也无。
在一些公司里，大家觉得让开发人员写文档是对其职业生涯的浪费。如果你在工程部门的最底层，迫切想要晋升，写文档可不是一个有性价比的晋升路径。
许多开发者不知道如何开始写技术文档，也不知道如何界定优秀文档
假如工程部门认识到了文档的重要性，那该如何开始编写呢？许多软件开发人员不知道如何编写有效文档，不知道优秀的文档应该是什么样的？有什么衡量标准？
文档内容杂乱无章
教大家编写技术文档的指南比较少。像"数据库连接" 和 "配置数据库"这样的行业术语，如果不在文档中提供适当的解释，前端工程师会很困惑。目前大部分文档编写缺少正确的用户体验研究策略，比如进行用户访谈或信息架构卡排序。
很多公司在编写文档方面投入时间过少，导致编写出的文档结构混乱。一个 90 天的项目，工程团队会花 89 天来编写和部署功能，仅用最后一天来编写文档，导致过个一两个月再去看文档，谁都看不懂，因为信息没有结构层次。
我们编写技术文档的目的是解决用户的问题。如果用户不能在文档中搜索到解决方案，就无法解决问题。好的文档必须有清晰的结构，方便用户快速找到自己需要的内容。我们要用信息架构来组织文档内容，这点我们会在后面进行更深入地介绍。
“文档读起来像是工程师写的”
糟糕的文档各式各样，而优秀的文档总是颇为相似。许多开发人员不知道什么是合适的语气。风格指南可以协助工程师、项目经理和 QA 团队用同样的口吻编写文档。
文档难以维护
很多工程团队都会面临文档过时的问题，怎么改善呢？
没有代码库的技术文档不利于获得贡献，千万不能有"眼不见心不烦"的心理。许多软件工程师把大部分时间都花在 Github 上。如果你把文档保存在 CMS 或 Microsoft Word （祝你好运）上，你会发现平台转换是个大问题。
我认为最直接的解决方案是采用"文档即代码"的理念，让文档与代码库共存。
琐碎的维护工作是另一个大家都要重视的问题。文档必须自有，就像功能或代码库一样。重视更新文档不能只喊口号，必须把更新文档作为项目最终阶段和验证的一部分，确保专人负责，保证及时更新 API 文档。
为什么技术文档很重要?
上文我们已经说了开发人员认为编写文档是一件出力不讨好的工作，怎么解决呢？
优秀的文档不一定能促成与大公司的合作，但糟糕的文档一定会阻碍你签署合同或成为一个市值 8 位数的公司。超过 80% 的团队领导承认，他们是根据文档质量做出买单决定的。
所以，一定要作出高质量的文档。那么，怎样才是高质量的优秀文档？
-
好的文档关注用户。
-
好的文档充满同理心。
-
好的文档能抓住时机。知道开发人员正在解决各种挑战，所以要在最合适的时间点为开发人员提供需要的概念。
如何改进技术文档
我们可以通过多种方法来优化文档，关键的几点是：
-
奖励编写文档的开发人员
-
明确什么是优秀的文档
-
实现文档维护的自动化
职业奖励
工程团队要承认技术写作的价值。要想让开发人员写作，就必须为编写文档划出具体时间，并将文档编写与奖金和晋升挂钩。
明确优秀文档的衡量标准
优秀文档不一定是主观的。如果你想要统一的文档风格，就要创建相应的风格指南。风格指南上列清楚技术写作规则和最佳方案。可以参考这些免费的优秀风格指南：
实现文档维护自动化
最后，尽量实现文档自动化。使用 Vale 和 Github Actions 等翻译器来梳理文档。如果你想让技术文档时刻保持更新状态，就把文档像代码一样放入 CI/CD 过程中。
原文作者：Portia Burton
原文链接：Improve technical documentation
