文件作為手冊與文件作為清單
我過去曾與我部門的其他人討論過文件，特別是詳細程度和要求。在他們看來，文件是當 X 件事情出錯時要做的 Y 件事情的簡單清單。
我不同意。我認為這假定 IT 中的所有問題都可以很容易地歸結為簡單的恢復程序清單。我認為它完全忽略了情況的複雜性，而且部門中的其他人並不總是對這個問題有深入的理解（這就是我寫文件的原因——所以他們有一些東西可以參考) 文件應該包括一些基本的背景材料，例如：
- 相關（子）系統的用途
- 為什麼以這種方式配置它
- 實施設置/程序時預期發生的事件
- 可能導致程序失敗的潛在問題
但是，我對此持反對意見，因此需要將我的文件重寫為“按順序應用的步驟 ABC 將解決問題 X”的表格。 我經常聽到有人哀嘆它需要放在一張紙上。 嘗試通過單頁文件以這種方式向某人解釋 Squid ACL 的配置，包括故障排除。這只是作為恢復清單“等待寫入”的六份文件之一。
我提倡的方法真的太過分了嗎？或者他們是對的，我應該在這裡管我的事，給他們寫一個簡單的清單？我擔心的是，無論您如何編寫程序清單，它都無法解決需要係統管理員仔細考慮的問題。如果您花時間制定恢復程序清單，但最終無法解決問題（由於文件的關注範圍狹窄，還有一些不屬於文件的其他因素），以及文件是為了避免重新閱讀手冊頁、wiki 和網站，那我為什麼要通過這些議案？我只是擔心太多，還是這是一個真正的問題？
編輯：
該部門目前沒有服務台職位。文件的受眾將是其他管理員或部門負責人。
在寫我的時候，我一直致力於寫兩套三套。get-er-done 清單，附有更長的關於系統架構的附錄，包括為什麼事情會以現在的方式完成，上線時可能的癥結，以及抽象的設計假設。接下來是可能出現的問題及其解決方案的列表，然後是較長的部分，其中包含有關係統如何工作、為什麼這樣做的資訊，以及在發生特殊情況時有助於將人們引向正確方向的其他資訊。
在我的上一份工作中，我們被要求編寫 doc，以便即使是 1 級幫助台人員也可以恢復原狀。這需要檢查清單，這些清單通常在撰寫後 3 個月內就過時了。強烈敦促我們盡可能編寫故障排除指南，但是當應急樹中的分支超過三個時，您就無法在不抽象的情況下編寫該文件。
離開上一份工作時，我在離開前上交了一本 100 頁的“如何做我的工作”手冊。它包含抽象的東西、設計理念以及集成點。因為我大概是在為另一個將要取代我的系統管理員寫作，所以我的目標是那些能夠將抽象概念轉化為具體行動的人。
五年過去了，我發現我對此的看法發生了一些變化。Document as Manual和Document as Checklist在文件的層次結構中都有非常有價值的位置，並且都需要生成。不過，它們的目標受眾非常不同。
文件作為清單
這種文件的目標市場是想知道如何做某事的同事。它們有兩種類型：
- 只是想知道如何做一件事而沒有時間翻閱十五頁手冊並為自己找出步驟的同事。
- 步驟相當複雜，但只需要偶爾執行一次的程序。
急躁是第一種的驅動力。也許您的同事實際上並不想知道為什麼輸出必須通過 90 個字元的 perl 正則表達式進行管道傳輸，只是為了關閉工單。對於那些確實想知道原因的人，絕對要在清單中包含這樣的聲明，“要詳細解釋為什麼這個工作流程看起來像這樣，請點擊這個連結”。
第二點是針對不經常執行但包含陷阱的程序。清單就像一張地圖，可以避免只是隨波逐流的末日。如果清單保存在文件儲存庫中，則無需在舊管理員發送 HOWTO 時搜尋電子郵件。
在我看來，好的清單文件還包括有關可能的故障點以及對這些故障的響應的部分。這會使文件變得相當大並觸發 TL;DR 同事的響應，因此我發現將故障模式及其響應設置為清單中的連結而不是頁面本身會產生不可怕的清單。擁抱超文本。
文件為手冊
此類文件的目標市場是想要更多地了解系統工作原理的人。how-to-do-a-thing 風格的文件應該能夠從這個文件中派生出來，但更常見的是，我認為它是對清單式文件的補充，以支持工作流程中做出的決策。
這是我們包含此類耐嚼部分的文件，例如：
解釋為什麼它是這樣配置的。
- 本節可能包括非技術問題，例如圍繞整個設備的購買和安裝方式的政治。
解釋常見的故障模式及其響應。
解釋任何書面和事實上的服務水平協議。
- 事實上：“如果這在決賽週失敗了，那就是一個放棄一切的問題。如果在暑假期間，回去睡覺並在早上處理它。”
設定升級和重構目標。
- 以後的政治可能不一樣，我們為什麼不把一開始介紹的一些不好的想法改正呢？
這對於全面了解整個系統非常有用。您不需要全面了解來執行簡單的人工自動化任務，您需要它來弄清楚為什麼某些事情會破壞它的做法，並知道在哪裡讓它不再這樣做。
您還提到了必須作為清單的災難恢復文件。
我明白，你有我的同情。
是的，DR 文件確實需要盡可能像清單一樣。
是的，DR 文件對清單的抵抗力最強，因為有很多事情可以破壞。
如果您的 DR 清單如下所示：
- 打電話給達斯汀或凱倫。
- 解釋問題。
- 退後。
你有問題。這不是一份清單，而是承認這個系統的恢復非常複雜，需要架構師才能弄清楚。有時這就是你所能做的，但如果可能的話，盡量避免它。
理想情況下，DR 文件包含一些不同內容的程序清單：
- 分類程序以找出問題所在，這將有助於辨識…
- 某些故障情況的恢復程序。哪個支持…
- 預先編寫好的恢復腳本，以幫助最大限度地減少恢復過程中的人為錯誤。
- 關於失敗案例、它們發生的原因以及它們的含義的手動式文件。
分類程序有時是您可以為某些系統製作的所有 DR 文件。但擁有它意味著凌晨 4 點的呼叫將更容易理解，進行恢復的高級工程師將能夠更快地解決實際問題。
一些故障案例具有直接的恢復程序。記錄它們。在記錄它們時，您可能會發現以特定順序輸入命令列表的情況，這是編寫腳本的一個很好的案例；它可以將 96 點恢復程序變成 20 點恢復程序。在逐個操作映射恢復過程操作之前，您永遠不會知道是否可以編寫腳本。
當沒有恢復過程或恢復過程失敗時，故障案例的手動式文件是最後使用的備份工具。它提供了可能需要的 google 提示，以便找到遇到該問題的其他人以及他們為解決該問題所做的工作。