什麼是好的技術文件？

最近為了在技術鏈條中選擇合適的模組，我看了比較多的技術文件，發現不少產品的文件真是不咋地，屬於“純技術思維”的文獻，似乎就沒考慮使用者這邊的感受和想法。

文件直接決定了開發模組的學習曲線是否陡峭。學習曲線平緩，才讓人感覺好用，易用，方便入坑。學習上的認知障礙是怎麼產生的呢？為什麼使用者看了會覺得“稀裡糊塗”，覺得上手犯難，有挫敗感呢？因為裡面引入了太多“從天而降”的概念而不去解釋，想當然的預設使用者應該瞭解、知道，這怎麼可能。

我認為，一個好的、正常的文件，應該是問題導向的。畢竟使用者使用它，就是為了解決問題而來。應該先闡述的是大家面臨的公共問題和需求，還有它能解決什麼問題，到什麼程度，在什麼地方用，怎麼用，再說明我們用什麼方法做到的。

後面，再順帶引出，我們製造出這些方法，必須引入的概念和設計思路，這些概念背後是什麼意思。這樣，大家就容易理解其用意了。

然後，提供入門教程，順帶詳細解釋，裡面涉及到的自造概念的方方面面。它能帶來什麼，這麼設計好處是啥，等等。後面有進一步的深入教程、介面手冊、FAQ等等。

介面部分，除了介紹介面的具體使用，更應該有的，是整體的執行邏輯的說明和Demo。告訴使用者，這些API，是如何組合起來完成任務的，可以操縱的是哪些，在什麼時機。如果沒有這些，使用者很容易“只見樹木不見森林”，不知道整體的結構和設計邏輯，因為API只是“單詞”，不是更有深度的“句子和段落”。而如果知道這些使用方法，就會對產品更有信心，也更容易掌握它的使用方法。

一般我認識一個產品或者模組，都是先檢索產品名字 + 入門、教程，有了初步概念，再尋找最佳實踐，Faq，而文件應該提供這些內容，才稱得上合格。

我認為這才是順著認知心理規律的文件設計。而我看到的不少產品文件，都做不到這一點。典型的例子是：產品有一部分自我介紹和特性宣傳，提供了一個簡單的入門教程案例 – 有一些連這個Demo都沒提供。然後就是API羅列了，中間還夾雜著自造的一些概念名詞。

作為剛剛接觸這個產品的使用者，第一反應常常就是：它怎麼用呢？那些突然出現的“概念名詞”啥意思？為啥用它呢？估計不少使用者已經開始打了退堂鼓，不知道怎麼上手。

不得不說，即便是做技術，產品思維也是很重要的審視習慣，使用者視角必不可少。

作者部落格