目錄
- 測試您的說明的好處
- 整個過程
- 有權測試其他功能
- 測試的樂趣
- 核算必要的時間
測試您的說明的好處
測試您的說明的好處之一是您可以開始回答自己的問題。您無需打聽工程師的話，您可以打個電話，查看響應，然後自己學習。（但是，這假設應用程序的行為正確，但事實並非如此。）
很多時候，當您發現應該發生的差異時，您可以與工程師面對面並告訴他（或她）某件事情工作不正常。或者，您可以提出改進工作流程，術語，響應，錯誤消息等的建議。如果您只是在記錄工程師所說的話，或者只是從Wiki規範或工程師那裡複製信息，則無法執行此操作書面頁面。
當問題無法解決時，您可以識別並記錄問題跟蹤系統（例如JIRA）中的錯誤。記錄錯誤對整個團隊有幫助，並增加了您在工程師方面的信譽。將錯誤記錄到工程師的代碼中也非常有趣，因為它表明您已經發現“代碼之神”創建內容中的缺陷和錯誤。
其他時候，這些錯誤在您的文檔中。例如，在一個項目中，通過測試API調用，我意識到我的參數之一是錯誤的。該參數不是verboseMode，而是verbose。這種細微的差異是您無法發現的細節之一，除非您測試某些東西，發現它不起作用，然後著手找出問題所在。
如果您正在測試REST API，則可以使用curl，Postman或其他REST客戶端提交測試調用。保存調用，以便您可以快速運行各種方案。
當您開始運行測試和實驗時，您將開始發現哪些有效和哪些無效。例如，在一家公司中，在建立測試系統並運行了一些調用之後，我瞭解到我的部分文檔是不必要的。我認為，事實證明IT操作實際上是在進行此配置時，現場工程師需要自己使用特定代碼配置數據庫。
直到我開始問如何配置數據庫時，我才意識到這一點，一位工程師說我的聽眾將無法進行該配置，因此它不應該出現在文檔中。
像這樣的小事情，您可以在自己進行過程中學習，從而增強了測試文檔的重要性。測試對於編寫良好的開發人員文檔至關重要。永遠不要只說工程師對某事的看法。如果您遵循此建議並測試了所有文檔，那麼您將在“ API文檔”字段中獲得成功。但是，如果您只是抄錄工程師告訴您的內容，那麼您基本上將最終成為工程師的秘書。（有關更多信息，請參閱我的博客文章如何避免擔任工程師秘書。）
整個過程
除了測試各個端點和其他功能之外，從頭到尾遍歷整個用戶工作流程也很重要。
在一家公司工作時，直到我構建自己的應用程序並將其提交給Appstore時，我才發現了一些錯誤。我正在記錄一個為第三方Android開發人員設計的應用程序模板，該第三方Android開發人員為Amazon Appstore構建流媒體應用程序。為了更好地瞭解開發人員的任務和流程，我需要熟悉我要求開發人員執行的步驟。對我來說，這意味著構建一個應用程序並將我的應用程序提交到Appstore-從頭到尾的整個工作流程。
要構建示例應用程序，首先我必須弄清楚如何獲取應用程序的內容。我決定通過“編寫文檔”播客來錄製播客的視頻，並將該媒體用於該應用程序。
由於該應用模板不支持將YouTube作為網絡託管服務商，因此我從YouTube下載了MP4，並將其直接上傳到我的網絡託管服務商。然後，我需要構建用於與應用程序模板集成的媒體Feed。通過使用Jayway Jsonpath或XPath表達式語法將應用程序定位為目標，該應用程序模板可以從Feed中讀取所有媒體。
我用Jekyll建立了我的提要。（您可以在podcast.writethedocs.org/fab.json上查看基於JSON的供稿。）設置此供稿中最具挑戰性的部分是配置recommendations對象。每個視頻都有一些標籤。推薦recommendations需要顯示其他具有相同標籤的視頻。使JSON有效在那裡是一個挑戰，我依賴Jekyll論壇的一些支持。
有了媒體和提要之後，將它們集成到Fire App Builder中就很容易了，因為畢竟我已經為此寫了文檔。
將應用程序提交到Appstore很有趣，並且啟發了我以前不瞭解的開發人員工作流程的一部分。您可以在Amazon Appstore網站上查看“編寫文檔”播客應用程序。
這是您的Fire TV上的應用程序屏幕外觀：
選擇視頻時，會看到視頻預覽屏幕：
一切似乎都很順利，但是後來我發現了一些錯誤，如果我沒有將應用程序真正提交到Appstore中，我將不會發現它們。首先，我發現設備定位（在您的Android清單中列出某些功能以識別您的應用支持的Fire設備）不適用於Fire TV應用。（不過，此問題與應用模板沒有直接關係。）
我還發現了其他問題。儘管開發人員已經對應用程序模板進行了幾個月的測試，但他們尚未測試過將帶有應用程序模板的應用程序推送到Appstore中。事實證明，模板的應用內購買組件（默認情況下未激活或未配置）會自動觸發Appstore添加標籤，以指示該應用包含應用內購買。
這個應用程序內購買標籤使開發團隊感到驚訝，如果第三方開發人員正在構建的所有應用程序都顯示此標籤，將會引起很多問題。
開發人員說，用戶可以簡單地從應用程序中註銷該組件。因此，我修改了文檔以表明這一點。然後，我嘗試從應用程序中註銷該組件並提交了新版本，但是應用程序內購買標籤問題仍然存在。
這種經驗使我更加了解，掌握所記錄的代碼並儘可能真實地運行它至關重要。令我震驚的是，工程團隊實際上沒有使用此模板發佈的Appstore中有一個應用程序。我是唯一的一個。
並非總是可以在實際情況下運行代碼，有時我可能只將角色限制為僅編輯和發佈，但這不是我更喜歡的情況。我喜歡動手編寫代碼，它可以在為其設計的方案中工作。真的，您還能如何寫出好的文檔？
該團隊還聲稱可以將同一應用提交到Google Play應用商店中。但是，這是未經檢驗的假設。當我將我的應用提交到Play商店時，Google拒絕了該應用，原因是該應用缺少清單中聲明的標語資產。它還觸發了“危險許可”警告。我將信息轉發給了工程師，他們創建了JIRA故障單來解決這些問題。這種測試不僅可以創建更好的文檔，還可以使我改進自己記錄的產品。（這也提高了我在工程師方面的信譽。）
相同類型的場景也經常在其他項目中重複出現。我支持的另一個工程團隊還開發了一個應用程序模板（網絡而不是Android），用於在Appstore中發佈應用程序。該工具是為非技術性最終用戶設計的，應該很簡單。除了簡短的常見問題解答，項目團隊甚至沒有計劃任何文檔。
我通過創建工具並提交應用程序從頭到尾測試了該工具。到我結束時，我已經遇到了30多個問題，並且發現了幾個重要問題。我發現了許多以前未知的錯誤，這些錯誤引起了人們對同步問題的關注，並召集了來自各個組織的團隊來解決一些問題，並且通常將我的價值從單純的文檔編寫者提升為多個團隊中的強者。
有權測試其他功能
為開發人員測試文檔非常困難，因為我們通常只提供參考API供用戶集成到自己的應用中。我們假設開發人員已經擁有應用程序，因此他們所需要的只是API集成信息。但是很多時候，直到將其集成到示例應用程序中並從頭到尾在完整場景中使用API之前，您都不知道API的問題。
例如，對於不使用應用程序模板的普通Fire TV用戶，我還編寫了有關如何集成和發送建議的文檔。但是，由於我沒有自己的常規Fire TV應用（不是使用Fire App Builder構建的）來進行測試，因此我沒有花時間去發送建議。根據工程師的說明以及我們從Beta用戶那裡獲得的反饋，我不得不相信自己的大部分信息。
可以想象，後來我發現了需要解決的文檔空白。事實證明，實際上您將建議發送到Fire TV主屏幕時，Fire TV僅使用您提交的一些建議信息。但是在我的原始文檔中，我沒有指出實際使用的字段。缺乏信息使開發人員想知道他們是否正確整合了建議。毫不奇怪，在我們的論壇中，第三方開發人員很快就問自己在做什麼錯，因為在顯示中似乎忽略了他正在傳遞的字段。
毫無疑問，將所有建議API調用從頭開始整合在一起的應用程序需要付出更多的努力。但是要編寫更好的文檔，這是我需要採取的步驟，以找出用戶可能遇到的所有潛在問題。如果創建示例應用程序超出了您的技術水平，請要求工程師提供演示應用程序或安排會議以現場演示該功能。
總體而言，請確保儘可能真實地測試要記錄的代碼。您會驚訝於發現的一切。向您的團隊報告問題將使您的產品更強大，並增加您對團隊的價值。
測試的樂趣
測試您的指令使技術寫作事業更加引人入勝。我什至要說，測試所有文檔都是將技術寫作從枯燥，半獨立的職業轉變為與您的團隊和用戶互動，互動的角色。
沒有什麼比成為工程師秘書更糟糕的了，您的主要任務是記錄工程師的言論，寫下筆記，發送給他們以供審核，然後聆聽他們的每句話，就像他們是皇帝給您的一樣大拇指或大拇指朝下。那不是激勵我的技術寫作工作。
相反，當我自己瀏覽這些說明並確認它們是否有效時，可以根據需要更清晰或更詳細地進行調整，這時事情變得很有趣。（實際上，我對知識領域本身（例如技術，產品前景，業務和行業等）瞭解得越多，技術寫作的吸引力就會大大增加。）
相反，如果您僅堅持進行技術編輯，格式化，發佈和策展，那麼這些活動在您的技術寫作生涯中可能將無法滿足您（即使這些活動仍然值得）。只有當您的突觸在您所寫的知識領域中觸發，並且動手進行骯髒的測試並嘗試所有步驟和過程時，技術寫作的工作才能活躍起來。
核算必要的時間
請注意，您自己和與用戶一起嘗試這些說明會花費一些時間。它可能會使記錄時間增加一倍或兩倍。編寫詳盡，準確的說明來解決具有不同設置，計算機和目標的用戶很乏味。您不一定總是有這個時間才能發佈。
但是不要以為一旦發佈您的產品，所有文檔都已完成。您總是可以回顧現有的，已經發布的文檔並進行改進。考慮第一個版本是您的文檔的“第一天”。這是第一次迭代。您的文檔將隨著每次迭代而變得更好。如果您無法在第一個版本之前啟動並運行測試系統，那就可以了。為即將發佈的版本構建測試系統。
在第一個版本中，如果您可以在使用文檔時捕獲反饋（來自論壇的反饋，聯繫電子郵件，日誌和其他方式），則可以改進文檔並查看可能遺漏的空白。在某些方面，用戶每次查閱文檔以執行任務時，都在測試您的文檔。（有關獲取反饋的更多信息，請參閱我的文章“重建缺席用戶”。）
除了自己測試文檔之外，您還需要針對用戶進行測試。
閱讀更多 沙場點兵見穹蒼 的文章
