編寫好的文檔入門

已發表: 2015-06-06

這篇文章是由客座作者 Jeff Matson 貢獻的。 Jeff 是 GravityForms 的文檔負責人。他是 Heartbeat Control WordPress 插件的創建者，是 90 年代的粉絲。

通常，文檔是開發過程中最被低估的部分。當我們查看 WordPress 社區中的搖滾明星時，我們通常會查看開發人員、設計師和營銷人員。對於那些為確保一切順利進行而流血、汗水和眼淚的文檔編寫者知之甚少。

這篇文章是關於那些日復一日地盯著沒完沒了的代碼行來破譯開發人員的想法的人，以及存在的代碼背後的真正含義。

好的文檔不僅僅是文字

優秀的文檔編寫者提供的不僅僅是指導手冊，他們還提供了一種體驗。我認識優秀的記錄者，指導過的初學者，他們之間最大的區別是了解閱讀者的大腦。就像小說一樣，文檔有一個流程，可以讓讀者保持興趣並吸收比他們意識到的更多的信息。

質量文檔針對最有可能閱讀它的用戶。它還為那些不太可能閱讀它的人提供了一個參考點。例如，如果記錄一個特定的鉤子，通常假設開發人員會閱讀它，但是那些沒有開發經驗的人呢？

一個好的文檔編寫者將為那些需要更多推動正確方向的人提供參考點，而無需聯繫支持人員為他們詳細說明。

大多數人只是簡單地忽略文檔，將其推入無盡的深淵，直到他們再也無法忍受。在某些情況下，我也犯了同樣的罪。這些人沒有意識到，每當他們的插件或主題未記錄在案時，用戶體驗就會受到影響。

讓我們來看看您最常見的支持票。如果你能更好地記錄這個問題，這些票會完全消失嗎？可能不是。您是否會減少有關該問題的票證並提高您或您的支持代理的工作效率？我保證。我認為我們都可以使用更少的支持票。

正如我之前提到的，文檔對用戶體驗產生了巨大的影響。如果用戶能夠輕鬆有效地找到信息，他們就節省了自己和您的時間。世界平均預期壽命為 66.57 歲，您的用戶寧願在生活中做點別的事情，也不願擺弄寫得不好的文檔。

如果客戶看到您在文檔中投入了相當多的時間和精力，那麼無論是否有意識，他們都會更加感激您。良好的文檔表明您在首次銷售後關心他們。

您是否曾經在花掉血汗錢後感到高高在上，很快就後悔購買了？我想我們都有。通過適當的文檔，您可以避免將這種感覺傳遞給您的客戶。

第一步是停止避免它。一旦你擅長它，編寫文檔比你想像的更愉快。事實上，它將成為第二天性。就像世界上的其他事物一樣，熟能生巧。

在決定將文檔提升到一個新的水平時，您首先要採取的步驟之一就是確定您的痛點。你在聯繫什麼？如果你開始盲目地寫東西，你可能會發現你寫的東西並沒有產生你想要的影響。

我發現的最佳技術之一是跟踪記錄的票證數量與未記錄的票證數量，並將未記錄的票證分類。這樣，您可以更好地針對您的痛點，並修改可能沒有應有的幫助的部分。

在確定了應該編寫的文檔之後，您應該確定目標受眾，並將其分解為開發人員、用戶和高級用戶。這可以幫助您迎合特定的受眾。稍後我們將討論如何定位這些用戶。

接下來，您要分解文檔。對於開發人員，您需要將其分解為原始信息（接受的參數、返回值等）、特定示例和用例。對於用戶來說，最好的做法是演練。他們需要採取的每一步，無論看起來多麼微不足道，都是至關重要的。

在每一步都向他們說明。為高級用戶編寫文檔與用戶場景非常相似，但更具結構化和可掃描性。要清楚，但要讓他們輕鬆跳到他們需要去的地方，而無需先閱讀上一步。

當談到編寫文檔的藝術時，請以最適合您的受眾的方式編寫，但也要使用您知道他們會理解的簡單語言。最好的原因之一是翻譯。雖然谷歌翻譯做得很好，但翻譯五年級學生的簡單詞彙比翻譯研究生論文中的詞彙要容易得多。

在您的內容中，不要害怕鏈接到相關內容。這將使您避免重複閱讀多個文檔，並允許讀者在需要有關特定主題的更多信息時回溯。畢竟，您的主要目標是讓用戶滿意，並節省自己的時間。

按下發布按鈕後，文檔過程不會停止。返回並根據需要修改每個文檔。幾乎在文檔發布後立即返回並查看您跟踪的支持票是否下降，以及該特定文章的訪問量是否增加。通常，如果您的文章獲得更多訪問量，這會有所幫助。如果您獲得更多流量但支持票證數量相同，您可能需要查看該文章以了解原因。

首先，我希望在做到這一點之後，您對那些在戰壕中編寫我們大多數人認為理所當然的文檔的人有更好的理解。它確實是一種藝術形式，我們中的許多以編寫文檔為生的人真正享受並投入了很多很多時間。

我也希望您從這篇文章中走出來，更多地思考您現有的文檔以及如何改進它。正確的文檔可能會非常有益，並且一旦在實踐中，編寫起來實際上會很有趣。

儘早記錄，經常記錄。一個偉大的產品不僅僅是偉大的代碼，它也有精美的文檔。