G24 英文字典vs英文課程──API Reference vs Tutorial

當我們開發好系統後，要如何讓其他原先不懂的人明白如何使用系統內部的程式來做出想要達成的動作呢？最理想的方式莫過於使用Tutorial循序漸進地來引領大家慢慢瞭解系統的內部。

公司的產品剛做出來時，提供給相關的專案作客製化時，專案人員抱怨說新的產品不知道要怎麼用，不清楚有哪些API。的確，產品剛出第一個版本時的說明文件少得可憐，做出來的說明文件坦白說實在有點不知所云，連我看了都不懂裡面的狀況，更何況資歷更淺的人呢？

有人提議說把教學文件做好一點就夠，但是我堅持應該要有系統所有的API參考文件。Tutorial就像是課本，會說明其他人所希望知道的系統，可是教學不可能教全部的東西，應該另外有一份所有東西的參考資料存在；就像英文字典會收集世界上所有的英文單字，而我們的英文課本只會選擇出英文字典裡最基本，最需要學會的一些單字來教學。

API Reference與功能清單很類似，後者是列出系統全部可以做到的事，前者則是列出系統內部可以使用的Class與方法；相同的是兩者都需要記錄才有可能寫出內容，這是直接把想法寫成程式的作法難以做到的。