關於編寫技術規範文件
在編寫代碼以解決除最瑣碎的軟件問題外的所有代碼之前，軟件工程師應編寫技術規範。
一些軟件工程師可能會認為編寫規範是不必要的過程，會妨礙敏捷方法的發展。技術規範的目的不是阻礙進步，而是退後一步並仔細考慮。記得：軟件工程師的工作不是寫代碼，而是 解決問題。
技術規範會迫使您思考複雜的問題並使每個人都在同一頁面上。這有助於避免在無用的解決方案上浪費時間或構建錯誤的東西。
還有其他好處：
- 提高估算和時間表的準確性。
- 考慮運營和長期支持成本。
- 防止安全和隱私問題。
- 為將來的團隊提供文檔。
經驗豐富的工程師知道，他們的大部分時間都不會花在編寫代碼上。留出時間思考問題，計劃和溝通是合理的。技術規範是實現這一目標的絕佳工具。
本文旨在（無論從結構上還是從內容上）跟隨Gaurav Oberoi撰寫的有關最佳軟件實踐的出色文章：
理想情況下，技術規格應基於可靠的產品規格。（或者經常發生的情況是，產品經理向工程負責人顯示產品規格草案，然後由工程師編寫技術規格草案，這會導致對功能，SLA和假設的一些誤解。這可能是最健康的方法。）也就是說，許多組織還沒有完全弄清產品管理，或者不認為技術項目需要產品規格。如果不清楚項目的目的和要求，則需要戴上“產品經理”的帽子，然後將其固定下來。
首先: 舉一個例子
假設我們在：
適度的Web啟動。當前，我們使用網絡應用的默認框架發送電子郵件（例如註冊時的歡迎電子郵件）。
產品團隊希望我們改善交易電子郵件。他們沒有帶寬來給我們提供產品規格，而是提交票證：
當前，所有電子郵件均由工程部門擁有，並使用我們自己的服務器發送。這意味著市場營銷和產品需要經過工程設計才能修改電子郵件並查看其外觀。我們已經收到關於可傳遞性較差的報告，但無法輕鬆驗證這一點。我們無法跟踪打開率和點擊率。添加新電子郵件需要2週以上的時間。我們要求這些改進：（1）營銷與設計可以編輯模板而無需進行工程設計；（2）跟踪開放率和可交付性的指標；（3）只需幾天就能插入新電子郵件。再過幾個月，我們可能想談談A / B測試。
而且您不編寫技術規範文件：
工程團隊舉行了一個富有成果的一小時會議：
- 使用我們自己的SMTP服務器發送電子郵件非常麻煩。我們應該切換到可以通過API觸發電子郵件的託管服務。
- 託管服務不僅應負責將HTML /文本發送到電子郵件地址（如Amazon SES），而且還應託管具有變量替換和簡單的if-then-else邏輯的電子郵件模板。
- 該服務將提供點擊率，打開率和可傳遞性指標。
該團隊決定使用MailChimp交易電子郵件，因為它是一項符合要求的多合一服務。它擁有可靠的記錄；和一些團隊成員熟悉MailChimp。
這似乎很簡單，因此您開始製定代碼。
這可行，但是…
隨著時間的流逝，我們遇到了一些問題。
- 我們的代碼中存在一個錯誤，該錯誤將同一封電子郵件連續10次發送給某些客戶。→ 糟糕！我們是否應該包括防護油門？
- 一些客戶抱怨說他們從未收到過我們的重要收據（是的，他們檢查了他們的垃圾郵件文件夾）。難道_我們_會犯錯誤，或者我們應該在我們的電子郵件服務提供商嚷嚷？→ 必須有可靠的記錄和可聽性。
- 業務團隊希望在客戶開始首次結帳時發送電子郵件。他們提交了一份工程票證，並希望它能在2天之內生效。→ 我們沒有對此過程設定期望。
- 我們不斷添加新的電子郵件。每個都有自己的模板和變量集。但是現在市場營銷希望對所有電子郵件都包括歸因跟踪，因此我們需要更新發送電子郵件的每段代碼。→ 嗯，也許我們應該標準化變量並使用通用機制發送。
- 我們的網絡應用程序正在作為網絡應用程序請求的一部分同步發送電子郵件，但是API調用有時很慢，因此會降低最終客戶的體驗。→我們應該如何以不影響用戶體驗的方式發送電子郵件？
- 我們的測試數據庫不小心拉了一些真實的客戶電子郵件。在測試過程中，我們向實際客戶發送了大量的分期電子郵件。→ 天哪！分期僅應將電子郵件發送給我們公司。
- MailChimp無法到達3個小時，我們的交易電子郵件也丟失了→ 我們需要監控和警報；我們需要一個中斷計劃。
相反，假設有一個技術規範。
這是我的示例技術規範。它定義了我們的目標和要求，然後逐步介紹了我們的方法。
這個例子在更長的方面。有點chat，因為解釋計劃的過程中有些時刻是“哦，是的，還有一些_要_考慮的……”
您是否已閱讀示例技術規範？如果您先閱讀了下一節，則更有意義。
如何編寫技術規範
在本節中，我將列出一些基本規則，然後逐步瀏覽示例中使用的模板。
基本原則
- 只有一位作者。可能會有很多團隊成員因他們的偉大構想而獲得讚譽，但是如果只有一個人將所有內容放到一個一致的提案中，這是最簡單的。
- 這不是手冊。一個技術規範可以映射未知的事物，但是並不需要計劃所有小事情。除非它們真的很重要，否則請避免深入了解棘手的細節，列出每個API等。
- 跳過無聊的東西。如果_您_認為自己寫的東西沒意思，那麼我保證也沒有人願意閱讀。
- 可以不完整。你_絕對_不允許的地方或列表部分為TBD手波。只需告訴讀者您正在做的事情，並確保在上線之前紮緊零頭。
- 假設沒有v2。相信您可以提出一個一次性的短期解決方案是普遍的謬論，因為重寫即將來臨。抱歉，這可能不會發生；系統往往會隨著時間的推移進行修補和擴展，但很少更換。調出可以在以後進行改進的組件和過程，但假定核心設計決策將持續很長時間。
標頭
標頭應包含項目名稱；日期; 作者; 和貢獻團隊成員。這些名稱和日期是未來幾年有用的令人驚訝的有用信息，當有人需要知道“嘿，誰知道如何維護這個笨拙的舊東西？”
總覽
總結項目並鏈接到外部文檔。
- 通過指出產品規格，營銷文檔和工程文檔來提供上下文。
- 總結一般方法。
- 給出總體時間估算（項目規模）。
目標和產品要求
如果產品規格已經明確定義了項目目標和要求，則這些部分是可選的。但如果沒有，那麼定義這些將是您的規格中最重要的領域。
所有成功項目的基石都有明確的目標-了解我們正在解決的問題。我不能高估達成目標的重要性；我所看到的最大的失敗是由於各個利益相關者奔向不同的方向，因為他們沒有花時間來確保每個人都_真正同意_他們應該做什麼。
對項目的正確工程響應是沒有目的的。## 假設條件
這是一個以工程為中心的項目符號列表，其中將產品要求摘要為技術行為和限制。它精確地告訴外部利益相關者您將構建什麼以及系統可以處理多少。要具體，詳盡和書呆子。定義SLA，容量和故障容限。
超出範圍
這是“假設”的對應詞，但否定的。這是列表中的項目符號列表，尤其是其中不包含的功能以及您將不擁有的內部流程。在此清單上花費大量時間，這是您避免不必要的工作和誤解的機會！
公開問題
在編寫技術規範時，不要停下來填寫所有漏洞和TBD項目。只需在“開放式問題”部分列出它們，然後繼續即可。
方法
詳細描述適合您和您的受眾的解決方案。每個子系統，新技術選擇，標準等都應有其自己的子節。您還應該描述您考慮的其他選項；或將其放在“考慮的其他選項”部分中。
組件
這是可選的，但建議使用。在這裡，您以易於理解的項目符號列表格式對提議的方法進行了概述，該列表列出了將要更改或創建的所有系統。
模式變更
列出所有數據存儲更改，無論多麼微小。您可以像提供完整的架構或UML圖一樣深入，但是我發現這種詳細程度會破壞早期的對話。最重要的是在高層上就要存儲的數據類型，應存儲的數據量和相關性達成一致，您可以稍後進行詳細說明。
安全與隱私
無論項目看起來多麼小，考慮客戶數據保護，個人信息，加密，攻擊媒介等總是一個好主意。始終包括此部分，以便人們知道您已經對此進行了思考，即使您只是說“這裡不應該涉及安全或隱私問題”。
測試計劃
描述您的工程團隊內部（單元測試和集成測試）和QA（手動測試計劃和自動測試套件）的測試策略。盡可能讓質量檢查小組提高警惕。
部署和推出
考慮上線的物流和操作順序；以及後續版本。討論配置管理，機密管理，數據庫更改，遷移以及您的註銷過程。
回滾計劃
說明如果部署出現問題（集成失敗或客戶討厭某個功能）會發生什麼。我們應該看什麼指標和警報？是否可以向後移動並恢復以前的系統？怎麼樣？
監控和記錄
顯示我們將如何知道我們的軟件是否存在問題，如何跟踪我們的SLA，如何確定係統是否正常以及能夠搜索日誌以跟踪錯誤或客戶問題。
指標
展示我們如何能夠回答有關功能優點和影響的業務級別問題。
長期支持
考慮以下問題：誰擁有該軟件的維護權？長期成本和“陷阱”是什麼？如果關鍵人物離開而我們需要轉移知識會怎樣？
時間線和組成部分
根據所有者，以日大小的估算值進行粗略的任務分解（例如，“合規性工程團隊創建小部件X：〜3個人日”）。現實點; 使用實際的人日曆天，而不是理論上的“如果我們100％關注……”的估計；並包括用於集成，風險和會議的填充。考慮所有團隊所需的任務，而不僅僅是您自己的。
沒有時間做規格了嗎？告訴鴨子。
好的，當然，沒有人有時間編寫技術規範。但是……這是一種精打細算，愚蠢的論點。如果您沒有時間刻意地思考問題，那麼您是否可以找時間修復錯誤並在以後支持一些限制？
至少在進入實施模式之前，請花幾分鐘與他人討論您的想法。任何人。
如果您的公司不相信技術規格，建議您購買橡皮鴨。在您的桌子上給它一個榮譽的位置（削減被動攻擊性怨恨）。當要求您開始一個新項目時，安排一個小時的會議室。將鴨子帶進會議室，然後小心地將其放在桌子的頭。然後開始和鴨子說話（是的，聲音很大）。說明您在做什麼，以及您認為最佳解決方案將是什麼。使用白板來繪製圖表-但要確保偶爾停下來並保持牢固的目光接觸。如果您說的話不太合理，請記下筆記，並感謝鴨子。
與橡皮鴨交談並不比編寫代碼要瘋狂。# 編寫技術規範就是編寫
寫作是需要實踐和紀律的技能，但值得付出努力。提高溝通能力對於成為更清晰的思想家和更好的領導者至關重要。您的第一個技術規格會進展緩慢；您只需要這樣做；然後再做一次 還有一個。變得容易了。
您知道誰擅長寫人們花錢讀書的東西嗎？斯蒂芬·金。我在工程生涯中讀過的最有用的一本書是他的回憶錄《寫作》。（＃2是Strunk and White的《風格的元素》，其次是Kernighan和Ritchie的《 C編程語言》）。金的書一半是令人痛苦的誠實自省，一半是關於工藝的粗俗實用建議。儘管他的主題是創意寫作，但我認為其中大部分適用於技術問題解決。我特別引起共鳴：
關門時寫，開門時重寫。換句話說，您的東西開始只是為您服務的，但是隨後就消失了。一旦[在那裡]，它便屬於任何想要閱讀的人。或批評它。如果您很幸運……前者比後者更願意做。
關上門寫。寫您的初稿時不要分神。將您的日曆清除幾個小時，關閉Slack，關閉手機，讓人們讓您獨自一人。焦點。並寫下您的想法。不要做太多修改，只是將您的想法表達出來，因此會有一個一致的敘述：“因為X，我們做Y”。
開門重寫。一旦您有了想法，就該開始協作了。分享您的草稿，獲取反饋，返回並填寫缺少的詳細信息。發現發現時，要保持透明，了解如何更新技術建議。
分享您的工作。在技術規範處於合理定稿的狀態後，將其發布。現在，最困難的部分是：讓人們閱讀它。
我的方法是：
- 我通過電子郵件和Slack發送我的技術規格，以盡可能擴大公司範圍內的通訊組列表，並徵求_任何人的_反饋。令人驚訝的是，誰做出了回應？通常其他團隊中完全無關的人只是好奇，或者初級工程師說他們學到了新東西。有時我發現我的建議正在重新發明輪子，或者我錯過了一些細微的問題。我從來沒有覺得自己分享了我的技術規格。
- 我列出了_利益相關者名單。_這些人擁有否決我的方法的合法權利。這包括產品經理，將使用我的新軟件的客戶以及將受到重大影響的團隊（請不要忘記DevOps，QA和安全性）。
- 我再列出感興趣的各方。這些人應該參與其中，包括我的經理，CTO，同行和服務所有者。
- 我安排了90分鐘的審核會議。利益相關者是必需的參與者，感興趣的參與者是可選的。會議邀請包括指向我的技術規格的鏈接，並將行程設置為：30分鐘的安靜時間以審核文檔（又是第一次閱讀文檔），55分鐘的討論時間和5分鐘的利益相關者簽署時間。
-
與往常一樣，請在評論部分中讓我知道您的想法！
Should We Write Tech Specs during the Software/ App Development?
