記錄 WordPress 插件和主題

已發表: 2017-03-17

文檔通常只有在出現問題並且您需要快速回答時才會受到讚賞。在本文中，我們將介紹為您的 WordPress 資產編寫文檔對您作為 WordPress 開發人員的實踐以及您發布的主題和插件的質量很重要的原因。

為什麼文檔很重要？

出於多種原因，保持有關您的項目、資產或產品的最新文檔集很重要。

首先，看到你 2 個月前製作的東西並且從那以後沒有接觸過的東西，並且不知道它意味著什麼，這是一種常見的體驗。當你開發它時，你的腦子裡已經有了它，但這種理解在未來不會存在。因此，無論是使用內聯代碼註釋還是在 Markdown 中編寫純文本註釋，都可以大大幫助您將來避免混淆。

其次，將您的資產記錄在案對其他 WordPress 開發人員很有幫助。即使你是一個孤獨的自由職業者，這也是有道理的（你一定會在某些時候與其他人合作）。他們要么需要使用這些資產，要么被要求維護和/或更新它們。不得不使用由其他人編寫的未記錄的代碼非常令人沮喪，他們不在身邊提供支持或解釋一些困難的部分。

最後，文檔為您的產品添加了“拋光”外觀，您的客戶會更愛您。

技術寫作本身就是一門學科，它用於以清晰明確的方式傳達技術信息。（不僅限於計算機，例如律師和醫生，也使用他們自己的技術語言）。出於這個原因，被認為是技術寫作的文檔通常遵循某種風格並遵守一套規則。

讓我們來看看最重要的 5 個，這樣您就可以為您的產品編寫有效的文檔！

喜歡使用比您通常在寫作中使用的更少的單詞：每個單詞都應該有一個目的。直接和簡單。當一個人遇到麻煩並想要快速找到解決方案時，通常會尋求文檔。例如，“無法銷毀對象 Q將導致內存洩漏”這樣的句子比“無法銷毀對象 Q將導致內存洩漏”更可取。
更喜歡使用主動語態而不是被動語態：“單擊右上角的按鈕”而不是“需要單擊右上角的按鈕”。使用主動語態可以消除關於誰做什麼的任何歧義。被動語態僅在您需要關注對象而不是主題時使用（例如， Pressidium 的平台是在考慮安全性的情況下構建的）。
當您需要描述概念時使用描述性語言，當您需要描述分步過程（如教程）時使用命令式語言。
當您需要列出沒有順序的事物時使用項目符號列表，當要點的順序很重要時使用編號列表。
在演示之前，請確保您自己測試了這些說明！

WordPress 插件就像任何其他軟件一樣。它們提供一定的功能，需要安裝，有時還需要故障排除。無論它們多麼簡單，提供足夠數量的文檔總是一個好主意，因為並非所有用戶都擁有相同的技術專長。

在 wordpress.org 上發布您的 WordPress 插件將為您提供一個放置安裝說明、屏幕截圖、常見問題解答甚至更新日誌的地方！用有用和高質量的信息填充它們是使您的插件變得更受歡迎的關鍵：

如果您遇到困難並需要一些靈感，請進行一項小型研究，看看文本是如何在具有數十萬安裝的流行插件中編寫的，與較少使用的插件相比。

記錄 WordPress 主題完全是另一回事。 WordPress 主題最常見的問題是不知道哪個部分對應於哪個視覺元素。不是每個人都精通 CSS：

創建 CSS 的所有部分的層次結構，並帶有相應的描述。
對於每個部分，添加一個帶註釋的屏幕截圖，詳細說明每個功能，以及一個小示例。在展示如何做需要用戶遵循說明的事情時，不要忘記使用主動語態和命令式語言。
使用諸如 css_doc 之類的工具來幫助您。這會生成 JavaDoc 樣式的文檔並且可以發布。
有時代碼註釋是不夠的，你需要為你的 CSS 主題創建一個樣式指南文檔。樣式指南文檔描述了元素的外觀以及在什麼情況下需要使用它們。它們強制一致性並使協作更容易。請參閱 Google 提供的此示例。
使用像 Blueprint CSS 這樣的 CSS 框架。這將通過為您提供一組工具來幫助您進行開發，例如可自定義的網格、有效的默認排版、瀏覽器 CSS 重置等等。
同樣，不要忘記查閱官方的 WordPress CSS 編碼標準。