我们的企业为什么写不好文档

昨天早上写的关于国产数据库文档质量太差的文章，实际上是被折腾的没脾气后的一种宣泄。我前天下午在分析一个等待事件的时候想起来想看看USTORE的性能，是不是像厂家宣传的那样比ASTORE好很多，于是就想找相关的资料看看，找了半天在官方提供的文档里就是找不到相关的描述。于是我只能去看数据库的参数，发现有个和USTORE建表相关的参数，再到百度上去请教了下度娘，找到一篇关于USTORE表创建的文章，照着做后发现使用USTORE后，BENCHMARK不到使用ASTORE的70%，和宣传的完全不符。于是我想再找找资料，结果一无所获，于是十分气愤地宣泄了一番。没想到这篇文章阅读量居然超过了2000，看来吐槽的文章远远比技术类的文章更受欢迎。

在评论区大家的评论也十分精彩，很多评论都很准确的实施了点穴。写文档的不懂技术，懂技术的不屑于写文档，这句话总结得相当准确。作为数据库产品的十分重要的一部分，如果企业真的不把它当成一件重要的事情来做，而是交给公司里的“低级”职员，甚至实习生来干，那么这个数据库产品在今后确实会“劝退一批数据库爱好者的”。

实际上一个数据库的技术文档，要写好确实是不容易的，因为数据库是一个十分庞杂的体系，既要把自己产品的基本概念和原理展现给用户，又不能把公司的核心技术机密透露的太清晰，这本身就不容易。再加上数据库体系十分复杂，应用场景和优化手段又千差万别，又要面对技术水平不同用户的不同的需求，确实不容易写好。我想即使是数据库产品的产品经理和总架构师都参与其中，也不容易把自己的产品介绍清楚。更何况我们的产品经理和总架构师，总监等高层级的人员是不屑于干文档这样的事情的。这就是我们看到的数据库文档质量不高的主要原因。

说数据库厂商不重视文档工作可能也不完全准确，不过在文档开发上投入不足是肯定的。我昨天早上写文章的时候比较气愤的是，我一向认为文档质量还不错的华为居然能产出如此低质量的文档。2018年我们的产品开始适配华为OCEANSTOR存储的时候，觉得华为的文档质量相当高，通过几份文档，我这个以前对存储完全小白的人也充分了解了华为存储的总体架构与监控运维的要点。甚至理解了很多华为存储指标为什么要这么设计，它能够在运维中发挥什么样的作用。不仅仅是我，连我们复杂开发这个模块工具的研发人员，都很快通过文档熟悉了华为存储，并在模拟器的帮助下，花了一个月时间就完成了第一个模型版本的开发。

数据库的文档只要足够重视，有足够的投入就能写好的吗？恐怕也不是这么简单的。对于写文档，我也是深有感触的。就拿我们自己的文档来说吧，虽然我十分痛恨文档写的不好的厂家，不过我们自己的文档也没写的很好。D-SMART也是一个十分复杂的产品，很多用户使用后都说功能很强大，但是很多功能要摸索很久才能知道藏在哪里。他们认真阅读了我们提供的文档，觉得依然对很多功能了解甚少。

当时我们写这份文档也费了不少劲，开始是研发部的人写，总也写不好，于是我们让一个使用D-SMART在一线为用户提供服务的DBA重写了文档。一线干活的人写出来的东西还真的不是盖的，一下子把两百多页的文档变成了400多页。内容是极大丰富了，不过里面大多数是贴图，文字内容依然质量不高。我当时感觉也没人能写了，于是利用空闲时间自己来改这份用户手册。经过图片的删减处理，添加了不少文字，篇幅减少到了300多页。不过我写文档也不专业，于是又把文档交给售前的同事进行优化。优化后的文档缩减到了200多页，不过更为清晰了，大部分图片也从不负责任的大图改成了局部小图，用户反馈也好了很多。这个工作总历时2年多时间，期间的艰辛也真的只有我们自己能体会到。虽然如此，这份用户手册的质量依然是不能让很多用户满意的。

不过五一后马上要发布的2.1版本又面临一个巨大的问题，菜单重新组织，功能模块重组，甚至首页都采用了全新的设计，这些变化也必须体现在文档中。我前阵子一直和同事们玩命赶研发的进度，对于文档修改这一块确实又疏忽了。文档编制不是一次性的工作，要随着软件的升级不断迭代开发，否则就会与软件发行版本脱节。我想五一节的时候，我可能也需要花点时间来协助文档开发人员一起来好好打磨打磨文档了。

文档工作量虽大，不过对于一个通用型的软件产品来说，是必须要做的。否则客户买了你的产品，很多功能不会用，那么大部分钱花得就冤枉了。实际上文档工作要做好虽然不易，不过做的认真一点，质量好一点还是有可能的，只要数据库厂商愿意在文档上进行投入。

数据库的文档，我们实际上有很好的老师，Oracle的文档已经深入人心了，也很适合大部分DBA与数据库研发人员的阅读习惯，我们在文档架构上学习下Oracle的经验就可以做的很不错了。

另外一方面就是架构师，产品经理亲自参与文档工作，为文档架构做出相应的设计，研发人员参与文档的评审工作，从而发现文档与产品脱节的问题。文档开发人员必须有数据库产品研发经验的具有数据库开发背景、具有数据库运维背景等多方面人员参与。

上面虽然只说了一些简单的要求，不过这些要求对于数据库厂商来说，已经很头痛了，这意味着成本，意味着人才。只有把人才和成本足够投入了，文档才能做好。不过作为一个如此重要的基础设施的原厂，这点投入都投不起的话，那也就是别去搞数据库产品研发了。