WordPress 專業人士的產品文檔

產品文檔通常被視為無關緊要的，您可以偷工減料。 它不被視為可以為客戶提供價值的東西，也不被視為可能影響收入和營銷等關鍵業務領域的東西。 當然，作為 WordPress 專業人士，您不需要像 Atlassian 或 Cisco 那樣編寫文檔。 通常，當人們想到“文檔”時，他們會聯想到厚厚的印刷用戶指南圖像，這些圖像按字母順序排列在一個沒有人閱讀的非常大的書架上。

但這已經改變：

隨著敏捷和 DevOps 的出現，發佈軟件變得更快，開發週期也變得更加動態。 因此，文檔現在反映了最新版本的當前狀態，而不是永遠寫在紙上的靜態內容。 文檔被集成到開發週期中，並且與軟件一樣頻繁地更新。

為什麼 WordPress 專業人士應該關心產品文檔？

有用的最新文檔不僅使用戶的生活更輕鬆，而且還增加了一定程度的潤色，成為獨一無二的營銷資產。 相反，糟糕的文檔會產生負面影響。 您可能自己也經歷過：您遇到了一個問題，您正在努力在文檔中找到解決方案，而當您沒有找到解決方案時，您最終感到沮喪（並且可能很生氣）。 如果您為產品付款，情況只會變得更糟。

如果您在 WordPress 代理機構工作，在項目的所有領域（從初始設計到資產）交付文檔，將增加一定程度的專業性，表明：

1. 你注重細節。
2. 你關心你的客戶，足以加倍努力。
3. 您對自己的設計和技術項目決策保持透明和自信。

MindTouch 營銷副總裁 Mike Puterbaugh 寫了一篇 Mashable 文章，描述了您的產品文檔是營銷資產的 5 個原因。 他總結如下：

這不是一項性感的事業，但它會讓你贏得同行的尊重、更有效的公司管理和更協作的團隊。 因為這不是關於本季度或今年，而是關於影響競爭優勢和長期增長。

現在我們已經建立了足夠的動力，我們將：

1. 探索與 WordPress 相關的不同類型的產品文檔。
2. 討論每種文檔類型的需求並提供可行的建議。
3. 就如何規劃和協作處理產品文檔提供一些初步指導。 特別是如果您在 WordPress 代理機構工作。

WordPress產品文檔的類型

WordPress 產品不僅僅是關於插件和主題。 在本節中，我們還將討論在線幫助、REST API 和一種叫做微內容的奇怪事物。

WordPress插件

WordPress 插件文檔需要迎合兩類人群：用戶和開發人員。 每個人的文檔需求都不同，使用的寫作風格也不同。

使用 Pressidium 託管您的網站

60 天退款保證

查看我們的計劃

用戶

用戶的文檔需求主要圍繞故障排除和配置。 除此之外，您需要以有吸引力的方式展示您的插件，以便讓用戶試用。 每個插件在 WordPress 插件市場都有自己的頁面。 請記住以下幾點：

• 寫一個引人入勝且有用的描述，鼓勵下載和使用。
• 從您的儀表板插件配置頁面添加帶有說明的帶註釋的屏幕截圖。
• 在常見問題解答中提出有用而不是陳詞濫調的問題。
• 擁有更新且編寫良好的變更日誌。 不要在那裡添加神秘或簡潔的註釋。

您應該記住，當用戶使用文檔時，他們可能急於尋找解決方案。 寫清楚，簡單，簡潔。 不要讓他們比現在更難。

開發者

除了遵循最佳軟件實踐和官方 PHP 編碼標準外，您還應將注意力集中在以下方面：

插件鉤子

這些完成了修改 WordPress 行為的工作。 很可能您的 WordPress 插件使用了這些。 由於插件掛鉤是代碼的重要組成部分，因此您應該記錄如何使用它們以及它們涉及的 WordPress 功能。

模板標籤

模板標籤是 WordPress 插件增強功能的另一種方式。 記錄您編寫的模板標記函數。 包括有關其他用戶或開發人員如何在其 WordPress 網站上使用標籤的示例。

選項

選項是一種在 WordPress 數據庫中存儲特定信息的方法。 這是通過 add_option 和 get_options 函數完成的。 在這種情況下，記錄您傳遞給這些函數的參數。

數據庫

插件經常從數據庫中讀取和寫入許多不同的東西。 由於這些是基本操作，因此記錄它們將極大地幫助其他開發人員了解您的插件是如何工作的。

WordPress 主題

您可以在兩個不同的區域為主題創建文檔。 首先是源文件。 帶註釋的 CSS 文件比沒有註釋的 CSS 文件更容易理解和閱讀。 使用諸如 css_doc 之類的工具來幫助您。 這會生成 JavaDoc 樣式的文檔，並且可以發布：

另一個領域是風格指南。 這些文檔描述了元素的外觀以及在什麼情況下需要使用它們。 它們強制一致性並使協作更容易。 您可以閱讀 Hubspot 的 20 個令人驚嘆的品牌風格指南示例文章，因為它包含許多很棒的示例。

同樣，不要忘記查閱官方的 WordPress CSS 編碼標準。

如果您是 WordPress 代理商，那麼詳細記錄設計元素也有助於新員工的入職。 樣式指南可用作新的和過去的客戶工作的教程或參考材料。

網上幫助

由於在線幫助旨在解決特定的用戶問題，因此從常見任務和問題列表開始是可行的方法。 儘管最初的清單並不詳盡，但請花時間製作盡可能多的具體項目。 這個想法是為這些任務和問題中的每一個編寫一個在線幫助文件，並將它們超鏈接到相關信息。 您可以創建用戶旅程來規劃用戶在您的應用程序中可以採取和執行的不同路徑。 深入研究支持電子郵件以注意常見問題和有問題的領域是使您的知識庫保持最新和有用的好方法。

Barry J. Rosenberg，Spring into Technical Writing 一書的作者提供了以下建議，以便編寫好的幫助文件：

使每個幫助文件盡可能簡短。 喜歡編號列表而不是項目符號列表。 不要離題，不要腳註，不要隨意。 讓每個幫助文件專注於單個離散任務。

微量內容

微內容有兩個定義：第一個是用戶瀏覽的標題和部分等內容，以便了解特定文章的要點。 第二是可以獨立存在並用於增強用戶體驗的小內容。 我們想到的一個特別好的例子是 Slack 的“幾個人正在打字……”位。 （儘管 Slack 充滿了優秀的微內容）。

當超過 3 個人同時在同一個頻道中輸入時，就會觸發該位。 Slack 不僅打印了當前正在輸入的人員列表，還獲取了這條無聊的信息並為其添加了一些樂趣。 討論開始變得非常激烈，它表明了這一點。 這是一個很好的例子，說明產品文檔（應用程序消息是其中的一部分，不是嗎？）讓人們談論你（並創建像上面這樣的搞笑模因）。

REST API

記錄 REST API 本身就是一門獨立的藝術。 與所有技術寫作一樣，您應該以定義簡潔、清晰和簡單為目標。 由於 REST API 有自己的格式和復雜性，因此您最好學習一下 Tom Johnson 在他的 Id rather Be Writing 博客上編寫的優秀的 API 文檔指南。

協作和規劃文檔

最終，文檔應該成為產品設計的一部分。 因此，您應該將其視為在您的軟件週期中有一個額外的管道。 這意味著使用軟件存儲庫來存儲最新的文檔版本，使用錯誤/問題跟踪器來監控任務和問題，將文檔項目規劃納入您的路線圖，最後但並非最不重要的是，與其他人協作。 如何開始的大致輪廓如下：

1. 記錄用戶想知道的所有內容，以及您需要為其編寫文本的區域。
2. 擁有所有內容後，將它們按類別分組並形成文檔標題。
3. 為每個文檔寫一個規範，詳細說明諸如標題、描述、目標受眾、媒體（文檔將具有什麼形式）、長度、需要多長時間等。
4. 將文檔規範中的估計添加到您的項目計劃中。

由於產品文檔涉及所有領域，因此幾乎可以肯定您需要與組織內的不同人員一起工作。 坐下來就所有這一切將如何進行的某種過程達成一致是個好主意。 與每個項目一樣，您應該確定將提供技術援助的利益相關者，以及將審查和編輯更改的利益相關者。

使用 Pressidium 託管您的網站

60 天退款保證

查看我們的計劃

這個過程應該有不同的階段。 這些應標出信息的收集地點、文檔的編寫時間、文學校對的準備時間、技術評論的時間、出版時間等。 強調文學、技術和與內容相關的評論之間的區別。 例如，當您要求團隊負責人對您的文檔發表評論時，它並沒有真正有用，而不是技術相關的信息，您需要語法和標點符號。

結束

產品文檔是一種可以長期獲得回報的資產。 它為您的客戶帶來價值。 它甚至可能非常好，例如 Stripe 的 API 文檔，以至於人們在論壇上對它贊不絕口。 這可以建立參與度並以自然而有力的方式宣傳您的品牌和產品。 當與創意微內容相結合時，它實現了 Mike Puterbaugh 所說的產品文檔是“營銷的秘密武器”的意思。