最近为了在技术链条中选择合适的模块,我看了比较多的技术文档,发现不少产品的文档真是不咋地,属于“纯技术思维”的文献,似乎就没考虑?#27809;?#36825;边的感受和想法。

文档直接决定了开发模块的学习曲线是否陡峭。学习曲线平缓,才让人感觉好用,易用,方便入坑。学习上的?#29616;习?#26159;怎么产生的呢?为什么?#27809;?#30475;了会觉得“稀里糊涂?#20445;?#35273;得上手?#25913;眩?#26377;挫败感呢?因为里面引入了太多“从天而降”的概念而不去解释,想?#27604;?#30340;默认?#27809;?#24212;该了解、知道,这怎么可能。

我认为,一个好的、正常的文档,应该是问题导向的。毕竟?#27809;?#20351;用它,就是为了解决问题而来。应该先阐述的是大家面临的公共问题和需求,还有它能解决什么问题,到什么程度,在什么地方用,怎么用,再?#24471;?#25105;们用什么方法做到的。

后面,再顺带引出,我们制造出这些方法,必须引入的概念和设计思路,这些概念背后是什么意思。这样,大家就容易理解其用意了。

?#32531;螅?#25552;供入门教程,顺带详细解释,里面涉及到的自造概念的方方面面。它能带来什么,这么设计?#20040;?#26159;啥,等等。后面有进一步的深入教程、接口手册、FAQ等等。

接口部分,除了介绍接口的具体使用,更应该有的,是整体的运?#26032;?#36753;的?#24471;?#21644;Demo。告诉?#27809;В?#36825;些API,是如何组合起来完成任务的,可以操纵的是哪些,在什么时机。如果没有这些,?#27809;?#24456;容易“只见树木不见森林?#20445;?#19981;知道整体的结构和设计逻辑,因为API只是“单词?#20445;?#19981;是更有深度的“句子和段落”。而如果知道这些使用方法,就会对产品更有信?#27169;?#20063;更容易掌握它的使用方法。

一般我认识一个产品或者模块,都是先检索产品名字 + 入门、教程,有了初步概念,再寻找最佳?#23548;現aq,而文档应该提供这些内容,才称得上合格。

我认为这才是顺着?#29616;?#24515;理规律的文档设计。而我看到的不少产品文档,都做不到这一点。典型的例子是:产品有一部分自我介绍和特性宣传,提供了一个简单的入门教程案例 – 有一些连这个Demo都没提供。?#32531;?#23601;是API罗列了,中间还?#24615;?#30528;自造的一些概念名词。

作为刚刚接触这个产品的?#27809;В?#31532;一?#20174;?#24120;常就是:它怎么用呢?那些突然出现的“概念名词”啥意思?为啥用它呢?估计不少?#27809;?#24050;经开始打了退堂?#27169;?#19981;知道怎么上手。

不得不说,即便是做技术,产品思维也是很重要的审视习惯,?#27809;?#35270;角必不可少。

作者博客