最好的文件就是沒有文件

最好的文檔就是沒有文檔最好的文檔就是沒有文檔

在告訴我我有多嚴重之前,請先聽我說。

在過去的幾周中,我從軟體開發人員的角度閱讀了幾篇有關編寫良好的用戶文檔的文章。 閱讀這些年來寫的文檔的人經常告訴我這是一個擅長的領域。 但是,當我離開WordPress十多年的時候,我幾乎完全停止了編寫用戶文檔的工作。 似乎很少有用戶注意到或質疑為什麼沒有某些功能的逐步說明。

像許多WordPress插件和主題開發人員一樣,我堅信手頭有文件。 作為自2003年以來一直在擺弄代碼的人,文檔一直是我最好的朋友。 在我的整個職業生涯中,我至少寫了幾百篇教程或文檔頁面。 我出版了兩本開發書籍,第三本是技術編輯。 我可以肯定地說,我創建了一個或兩個插件,其內聯文檔比實際代碼多。

但是,我也為最終用戶提供了十多年的支持。 我可以肯定地了解到的一件事是,許多用戶根本不閱讀文檔。 即使他們正在閱讀,大多數時候也不需要。

儘管反覆嘗試,重新設計並盡一切努力使用戶在進入每個問題的支持論壇之前都可以找到文檔,但每天重複出現的問題都不會失敗。

我花了好幾年的時間-遠遠超出了應有的時間-才知道解決方案不在文檔中,問題不在於用戶的閱讀能力。 問題是產品。 如果用戶問的是重複問題,則意味著用戶體驗出了點問題。 最終,我轉移了注意力。 我沒有寫更多的文檔,而是專註於解決軟體中不斷出現的問題。

我失敗的活動是傾聽。

開發人員可以獲得的最佳技能之一就是能夠聽取用戶所說的內容,然後將其轉換為更好的代碼,用戶界面和用戶體驗的能力。

在我年輕的時候-我懷疑很多開發人員在開始時都是一樣的-我覺得我知道每個問題的答案並且總是正確的。 我非常熟練,而且我知道。 對於一個20歲左右的年輕開發者而言,這往往意味著麻煩。 這意味著您認為問題不在於所構建的東西。 不,問題在於用戶做錯了什麼。 這些類型的開發人員會說「 RTFM」,並向用戶指出無法解決其問題的過度技術文檔。

有些經驗教訓是很難學的,但要學習這些經驗,我們必須製造出更好的產品。

我保證,如果您要對用戶進行一項活動(聽,真正聽),您將花費更少的時間來解釋某項工作的原理。 您需要問自己的問題是,為什麼首先需要存在一個文檔。 如果用500個單詞來解釋一項功能,則很有可能該功能無法帶來理想的用戶體驗。

在構建產品時,我們應始終努力構建它們,以便不需要文檔。 或者,至少要構建它們,以便閱讀手冊是解決問題的最後手段。

出於實際目的,作為過去的全職開發人員,我保留了一個簡單的文本文件,其中包含重複的問題列表。 對於團隊來說,這可能是更複雜的設置,例如創建GitHub問題。 我的文本文件運行良好,因為我是一個單人表演。 我會養成例行檢查清單的習慣,並問我如何改進每個方面。 有些物品從未從清單上劃掉。 但是,我常常會從中學到關於首先為最終用戶進行構建的重要課程。 我可以看到腦海中有意義但又使他人困惑的事物。

最大的改進不是尋找現有問題的解決方案,而是根據過去的經驗來識別我正在開發的新產品中的問題。

隨著時間的流逝,我的大部分文檔都面向開發人員。 這些主要是關於使用API​​,掛鉤和其他與開發人員相關的功能的教程-插件UI並未公開這些內容。 我為最終用戶編寫的文章少得多,因為我根據他們的反饋和問題來更新項目。 是的,我有時會絕對失敗,但是作為一個能夠聽取問題並根據用戶自己告訴我的方式進行更改的人,我會變得更好。

當我說最好的文檔不是文檔時,我並不是說您應該完全跳過它。 我想問一個關於為什麼需要文檔的問題。 您可以採取哪些措施來簡化用戶體驗? 您是否在積極跟蹤支持問題並解決產品本身中的問題?

在開發中,我們經常談論編寫「自文檔代碼」。 這是一種寫代碼的方式,您不必通過內聯文檔向其他開發人員解釋代碼。 例如,WordPress中的wp_insert_post()函數告訴您其目的是插入帖子。 任何軟體的目標還應該是創建自文檔界面和用戶交互的其他元素。 用戶應該能夠自動理解按鈕,文本欄位或複選框的用途,而無需查閱文檔。

下次坐下來編寫新的面向用戶的文檔時,請確保您不會將其用作支撐不良用戶體驗的拐杖。

像這樣:

喜歡載入中……

資源

相關文章