軟體文件只是一組文章。 但即使是它們也會讓你發瘋。 首先，您花費很長時間尋找必要的說明。 然後你就能理解晦澀難懂的文字了。 你照寫的做了，但問題沒有解決。 你尋找另一篇文章，你變得緊張......一個小時後，你放棄一切並離開。 這就是糟糕的文檔的運作方式。 是什麼造成了這種情況以及如何修復它 - 請閱讀切口下方的內容。
我們的舊文件有很多缺點。 我們已經對其進行了近一年的重新設計，以便上述情況不會影響我們的客戶。 看， и .
問題一：文章表達不清、寫得不好
如果文件無法理解，那麼它還有什麼意義呢？ 但沒有人會故意寫一些難以理解的文章。 當作者不考慮讀者和目的、潑水並且不檢查文本錯誤時，就會發生這種情況。
- 聽眾。 在寫文章之前，您需要考慮讀者的準備程度。 合乎邏輯的是，在一篇針對初學者的文章中，您不應該跳過基本步驟並留下不加解釋的技術術語，但在一篇有關只有專業人士才需要的罕見功能的文章中，您應該解釋PHP 一詞的意思。
- 目標。 還有一件事需要事先考慮。 作者必須設定明確的目標，確定文章的有用效果，並決定讀者讀完後要做什麼。 如果不這樣做，您最終將只是為了描述而描述。
- 水和蟲子。 有很多不必要的資訊和官僚主義、錯誤和拼字錯誤幹擾感知。 即使讀者不是語法納粹分子，文本中的粗心也會讓他感到厭煩。
考慮一下上面的提示，文章將會變得更加清晰 - 保證。 為了讓它變得更好，請使用我們的 .
問題 2. 文章並不能回答所有問題
如果文件跟不上開發的步伐，不能回答真正的問題，而且其中的錯誤多年都沒有得到糾正，那就很糟糕了。 這些問題與其說是作者的問題，不如說是公司內部流程組織的問題。
文件跟不上發展
該功能已經發布，行銷計劃涵蓋它，但結果發現新文章或翻譯仍然不在文件中。 我們甚至因此不得不推遲發布。 你可以要求大家準時把任務交給技術作家，但這是行不通的。 如果該流程沒有自動化，情況就會重演。
我們對 YouTrack 進行了更改。 在功能開始測試的同時，撰寫有關新功能的文章的任務就落到了技術作家身上。 然後行銷人員了解這一點，以便為促銷做好準備。 通知也會發送到 Mattermost 企業通訊軟體，因此您不可能錯過來自開發人員的新聞。
文檔不反映用戶請求
我們習慣這樣工作：一個功能出來了，我們就討論它。 我們描述瞭如何打開、關閉它以及進行微調。 但是，如果客戶以我們意想不到的方式使用我們的軟體怎麼辦？ 還是其中存在著我們沒有想到的錯誤？
為了確保文件盡可能完整，我們建議分析支援請求、專題論壇上的問題以及搜尋引擎中的查詢。 最熱門的主題將轉移給技術作家，以便他們補充現有文章或撰寫新文章。
文件沒有改進
馬上就做到完美是很困難的，總是會有錯誤的。 您可以希望得到客戶的回饋，但他們不太可能報告每一個拼字錯誤、不準確、難以理解或未找到的文章。 除了客戶之外，員工也會閱讀文檔，這意味著他們會看到相同的錯誤。 這個可以用！ 您只需要創造方便報告問題的條件。
我們在內部入口網站上有一個小組，員工可以在其中留下有關文件的評論、建議和想法。 支援是否需要一篇文章，但它不存在？ 測試人員是否注意到了不準確性？ 合作夥伴是否向開發經理抱怨錯誤？ 都在這個組裡！ 技術作家立即修復一些問題，將一些問題轉移到 YouTrack，並給其他人一些時間思考。 為了不讓話題平息，我們不時提醒大家小組的存在以及回饋的重要性。
問題3. 需要很長時間才能找到合適的文章。
找不到的文章並不比找不到的文章好。 好的文檔的座右銘應該是“易於搜索，易於找到”。 如何實現這項目標？
整理結構，確定選題原則。 結構應該盡可能透明，這樣讀者就不會想“我在哪裡可以找到這篇文章？” 總而言之，有兩種方法：從介面和從任務。
- 從介面上看。 內容與面板部分重複。 舊的 ISP 系統文件中就是這種情況。
- 來自任務。 文章和章節的標題反映了使用者的任務； 標題幾乎總是包含動詞和“如何做”問題的答案。 現在我們正在轉向這種格式。
無論您選擇哪種方法，請確保主題與用戶正在尋找的內容相關，並以專門解決用戶問題的方式進行涵蓋。
設定集中搜尋。 在理想的情況下，即使您拼寫錯誤或語言錯誤，搜尋也應該有效。 到目前為止，我們在 Confluence 中的搜尋還不能滿足我們的要求。 如果您有很多產品並且文件很通用，請根據使用者所在的頁面自訂搜尋。 在我們的例子中，主頁上的搜尋適用於所有產品，如果您已經進入特定部分，則僅適用於其中的文章。
加入內容和麵包屑。 當每個頁面都有選單和麵包屑時，這是很好的——用戶當前頁面的路徑，並且能夠返回到任何級別。 在舊的 ISPsystem 文件中，您必須退出文章才能看到內容。 不方便，所以我們把它固定在新的上。
在產品中放置鏈接。 如果人們一次又一次地提出同一問題的支持，那麼在介面上添加一個提示及其解決方案是有意義的。 如果您有數據或了解用戶何時遇到問題，您也可以透過郵件清單通知他們。 向他們表示關心並減輕支持負擔。
彈出視窗的右側是有關在 ISPmanager 的網域管理部分中設定 DNSSEC 的文章的鏈接
在文件中設定交叉引用。 相互相關的文章應該有「連結」。 如果文章是連續的，請務必在每個文字的末尾添加前進和後退箭頭。
最有可能的是，一個人首先不會向你尋找問題的答案，而是向搜尋引擎尋找答案。 如果由於技術原因沒有指向文件的鏈接，那將是一種恥辱。 所以要注意搜尋引擎優化。
問題4.過時的佈局幹擾感知
除了糟糕的文字之外，文件也可能因設計而被破壞。 人們習慣閱讀寫得好的資料。 部落格、社群網路、媒體——所有內容的呈現不僅美觀，而且易於閱讀、賞心悅目。 因此，你很容易理解一個人看到下面截圖中的文字時的痛苦。
本文有太多截圖和亮點，沒有幫助，只會幹擾感知（圖片可點擊）
您不應該長時間閱讀帶有一堆效果的文檔，但您需要考慮基本規則。
佈局。 確定正文寬度、字體、大小、標題和填充。 聘請設計師並接受工作或自己做，請閱讀 Artyom Gorbunov 的書“版式和佈局”。 它只提供了佈局的一種視圖，但已經足夠了。
分配。 確定文本中需要強調的內容。 通常，這是介面、按鈕、程式碼插入、設定檔、「請注意」區塊中的路徑。 確定這些要素的分配並記錄在法規中。 請記住，分泌物越少越好。 當它們很多時，文字就會很吵。 即使是引號，如果使用得太頻繁也會產生雜訊。
截圖。 與團隊就在什麼情況下需要螢幕截圖達成一致。 絕對沒有必要每一步都進行說明。 大量螢幕截圖，包括。 單獨的按鈕，幹擾感知，破壞佈局。 確定螢幕截圖的大小以及突出顯示和簽署的格式，並將其記錄在規定中。 請記住，插圖應始終與所寫內容相對應且相關。 同樣，如果產品定期更新，就很難追蹤每個人。
文字長度。 避免文章過長。 將它們分成幾部分，如果不可能，請在文章開頭添加帶有錨鏈接的內容。 讓文章在視覺上更短的一個簡單方法是將一小部分讀者所需的技術細節隱藏在劇透下。
格式。 在您的文章中結合多種格式：文字、影片和圖像。 這將改善感知。
不要試圖用漂亮的佈局來掩蓋問題。 老實說，我們自己希望「包裝器」能夠保存過時的文件 - 但沒有成功。 這些文字包含太多視覺噪音和不必要的細節，以至於法規和新設計無能為力。
上述大部分內容將取決於您用於文件編寫的平台。 例如，我們有 Confluence。 我也不得不和他一起修補。 如果有興趣，請閱讀我們的網頁開發人員的故事： .
從哪裡開始改進以及如何生存
如果您的文件與 ISPsystem 的文件一樣龐大，並且您不知道從哪裡開始，請從最大的問題開始。 客戶不理解該文件 - 改進文本、制定法規、培訓作者。 文件已過時 - 請注意內部流程。 從最受歡迎產品的最受歡迎文章開始：尋求支援、查看網站分析和搜尋引擎中的查詢。
讓我們馬上說——這並不容易。 而且它也不太可能很快發揮作用。 除非你剛開始並立即做正確的事情。 我們確信的一件事是，隨著時間的推移，情況會變得更好。 但這個過程永遠不會結束:-)。
來源： www.habr.com