工作中遇到的写文档相关的问题和思考
不知道其他行业的工作中写文档是不是一个值得讨论的问题，但是在IT行业中，这绝对是一个值得好好讨论的问题。
在过往的工作的经历中，经常会遇到或者听到别人抱怨说某个系统或者API没有文档以致于很难甚至完全没办法接手工作的情况。
由于已经意识到这个问题，所以我自己在工作中会比较注意写文档这个事情，尽量把我觉得别人可能需要的了解的地方都写成文档，但发现还是有很多问题，今天写个笔记记录一下这些问题以及我的看法。
先直接说我观察到的问题，有以下几个：
- 怎么样让别人知道你为某个问题写了文档？
- 你写的文档是否能让读者看得懂？
- 怎么样维护这些文档？（主要是更新和管理这两个问题）
- 你写的文档是必要的吗？
老实说，我对于上面这几个问题都没有很好的解决办法，但是有一点自己感受和经验，接下来依次讨论上述几个问题。
怎么样让别人知道你为某个问题写过文档？
一般来说，不论是内部文档还是互联网上的文档，不会有人把文档通读一遍再开始工作，大家可以回想一下自己看文档的过程。以我自己为例，我一般是先看目录，然后找自己想要的部分去看，绝不会把文档从头到尾全部读一遍。
那么应该怎么让别人知道你关于这个问题写过文档呢 ？
以我最近一段经历为例。
我最近几个月开始负责公司的制品管理系统，我为了推广和让用户（公司的其他研发同事）熟悉这个系统，写了很多文档，从基本配置到权限管理，再到best practices，但还是经常遇到别人跑来问一些已经有文档的问题。
我们做了一点优化，感觉有点作用，优化项如下：
- 为文档创建一个索引
新建一个空白的文档，把所有其他文档的链接都放到这个文档中，并且为每个链接写一行描述，让读者知道这个链接里面记录的是什么问题，并且这个描述在准确的前提下要尽量简短。
这么做的好处就是读者不用为了查找一个问题的文档在不同的页面中跳转，减少了查找文档（不是查看）的阻碍。 - 创建一个客服系统
我们公司有一个对话系统，可以针对用户的输入，根据关键字返回对应的文档的链接。我为文档打上了一些标签（关键字），以便于用户在提问时，这个系统可以返回对应的文档。但是这个对话系统有点傻，效果不是很好（但是是有用的），所以目前这一块的工作主要是依靠另外一位同事帮忙的，他会根据用户的问题给出对应的链接。 但是chatGPT让我看到这个方法在将来一定会更有效。如果chatGPT出企业版，我们就可以根据自己的文档和FAQ去训练他，然后让chatGPT去回答用户的问题。 - 不定期对最近新建的文档和访问量比较多的文档进行推广
我们会不定期把我们最近新建的文档和访问量较多的文档发给用户（群里和邮件）。但是一定要把握频率，太频繁的话用户会觉得反感，会适得其反。
你写的文档是否能让读者看得懂？
写文档（包括写博客）的时候最容易犯的一个错误就是没有从读者的角度出发来写作。
我们往往会根据自己的知识和经验来写作，但是这经常会导致读者读不懂我们所写的文档。
一个最简单的验证办法就是找2-3个其他同事帮忙review一下文档，看看他们是否他们读得懂。
写作过程中有一个方法在一定程度上可以解决这个问题，那就是写每一篇的文档的时候都要考虑到零经验的读者，把当前文档中需要到的前置知识点和文档以链接的形式放到文档中，以便于读者需要的时候去查看。其实很多优秀的开源软件的文档就是这么做的。
怎么维护这些文档？
随着时间的迁移，我们写的文档越来越多，有一些可能已经过时了，那么应该怎么管理呢？
有的时候杂乱、过时的文档，对于工作是有危害的。比如系统参数作用的变化不及时更新的话，如果用户使用了一个破坏性的参数，其后果可能是致命的。
我把维护分为管理和更新两部分来写。
管理
我们公司一直使用的atlassian的wiki来写文档，其实一般来说这就已经挺好的了，可以按照组织架构和产品目录来编排文档，据说飞书也是可以做到类似的功能的。
最近团队中有一个小伙伴发现了一个新的方法来管理文档，我觉得很好，打算尝试一下。
把文档以markdown文件的形式放在github（我们公司自己的github）的仓库中，然后通过一个插件同步到wiki中，这么做有一个明显的好处就是有了版本管理的功能，因为atlassian的wiki本身是没有这么功能的。另外可以通过markdown来写文档，这一点对于程序员来说比较友好。
更新
维护文档另一个巨大的挑战就是更新，尤其是对公司内部发布的软件文档。
因为如果是商业软件，文档是一定要更新的，这既有来自于商业客户（甲方爸爸）的压力驱动，也有来自于市场的盈利（赚钱￥￥）驱动，所以往往保持商业软件的更新不是一个太大的问题。
但是对公司内部发布的软件，因为缺少上述两个驱动因素，所以想要保持文档更新就有点困难。
不过还是有两个可行的办法来尽量保持文档更新。
- 挑选团队中那些比较追求完美的人来负责内部软件
这类人往往因为追求完美，会主动去更新文档 - 建立文档review机制
至少对于那些非常重要的系统，应当建立文档review机制。
这有两个好处，一是可以保持文档应有的更新；二是可以让团队中其他人也熟悉这些文档，因为review的时候他们要参与，这样可以在一定程度上做到团队成员之间的backup。
你写的文档是必要的吗？
我在刚开始负责制品管理系统的时候，花了大量的时间去写文档，希望尽可能面面俱到，但是后来发现其中有一些文档是不需要的。
那要怎么样知道自己写的文档是不是必要的呢？
有两种方法，分别使用于写文档的前后。
写好文档之后，可以关注文档的阅读量，如果一直没有人阅读，或者阅读量非常少，就说明这个文档很可能不是必要的。（或者文档写的非常差）
写文档之前，可以先收集用户问题再开始写，避免按照自己的喜好开始写文档。