為什麼編寫軟件設計文檔很重要

恭喜，你是一個稱職的獨立開發者。 從你卑微的開始，也許是一名測試員，你已經發展成為一名團隊開發人員，然後是一名高級開發人員，現在你已經取得了另一個飛躍，也是最大的飛躍，直接與客戶合作。

但是在其他過渡是線性的情況下，最後一個是指數級的。 過去，您從與客戶一起工作或本身從事軟件業務的雇主那裡得到了您的進軍命令，但現在所有這些曾經在專家測試、程序管理等之間分配的職責都歸您所有。 現在您正在與不從事軟件業務的客戶合作； 他們在另一個需要軟件的企業中，他們對他們想要從你那裡得到什麼沒有一個清晰而準確的願景。 這是一個遠比看起來更大的挑戰。

*注意：* 在這裡，我描述的是希望從他們的開發人員那裡獲得一支單人軍隊的小型客戶。 這不是自由職業者可以走的唯一路線，也不是我們在 Toptal 合作的唯一客戶，但這是我最喜歡的路線。 當然，如果您是在團隊中工作而不是獨自工作，則以下某些內容將不適用。 例如，如果您使用敏捷方法或 Scrum，您可能希望構建您的里程碑稍有不同。

你們都聽說過溝通的至高無上的重要性。 你無法通過 Skype 獲得幾句話的簡潔描述，然後說“三個月後我完成後見”。 您必須與您的客戶保持溝通，並且在工作的每個階段都確保您對目標有一致的想法，因為確實很少有客戶會向您發送線框圖和詳細的功能規範。 您將對軟件的功能、外觀和流程有一個非常大致的了解。 如果您根據通常開始時的粗略描述編寫應用程序，那麼您的客戶幾乎不可能對結果感到滿意。 在每個階段，您都必須以更接近一致的方式進行迭代。

在自己從事軟件業務的公司工作多年，團隊中的每個人都來自相同的文化，說相同的母語，在同一個走廊工作，每天見面等等，值得注意的是公司仍然有一半的時間沒有得到它想要的東西。 別搞錯了：這裡的挑戰是巨大的。

為什麼軟件設計文檔很重要

因此，當您開始一個新項目時，甚至在您打開 Xcode 或 Visual Studio 之前，您就需要有明確且一致同意的設計目標。 並且這些目標應該在規範文件中建立。 如果客戶還沒有寫，你應該寫它，並在你打開你的IDE之前提交給他們審查。 如果你遇到一個客戶說，“我們沒有時間設計文檔”，坦率地說，你應該離開這個項目，因為你前面有麻煩。 規範不需要特別長； 它可以只有幾頁，但至少應該佈置用戶界面，包括線框（如果有 UI 組件），並設置完成里程碑。

沒有這份文件，你最終會陷入一個模棱兩可的循環，客戶會爭論他們告訴你的或你告訴他們的，憤怒地發送以前通信的剪切和粘貼，解釋和爭論，直到客戶要求的時候到來您進行更改以使應用程序符合“他們實際要求的內容”，並希望您免費進行這些更改。

有了這個軟件設計文檔，任何這樣的小問題你都會有答案：當出現分歧時，你可以參考客戶同意並簽署的規範，指出你已經完全履行了它。 您將對文檔進行修改和澄清，而不是憤怒的爭論。 如果有的話，客戶將首先為讓不精確性溜走而道歉。

我們都想要滿意的客戶。 我們都希望建立友好的工作關係。 我們都希望以出色的工作為榮。 但是，如果對工作的實際內容有任何模糊性，這些都無法實現。 如果您的客戶說設計文檔有太多額外的工作，那麼您的工作就是向他們解釋，當由於某種誤解需要進行修訂時，真正的額外工作將會出現。 如果客戶仍然堅持讓您在沒有此類文件的情況下提前，您應該接受您的關係不可行的事實並走開。

軟件設計規範實際上應該指定什麼？

至少，它應該是對所需應用程序、完成標準和里程碑的描述。 請記住，您共享的是最好描述為需求和功能文檔的內容，而不是實現規範。 除非特定的實現是明確的客戶目標，否則如何使其工作取決於您。

用戶界面

大多數項目是應用程序，而不是庫或框架。 但是，如果您碰巧將其中一個作為可交付成果，那麼算您自己幸運，因為用戶界面無疑是您的設計文檔模板中最有問題的組件，並且幾乎總是會導致誤解。 許多客戶會向您發送由非程序員的圖形設計師在圖形編輯器中創建的完美插圖。 但問題是：這些插圖沒有說明動畫、控制狀態（例如，這個按鈕是否被禁用？它在不可用時會消失嗎？），甚至是按下按鈕時要執行的操作。

在開始編寫這些插圖背後的代碼之前，您應該能夠回答所有這些問題。 具體來說，您應該知道：

1. 控件是否始終可見和/或啟用？ 他們的狀態在什麼條件下會發生變化？
2. 看起來像位圖——是按鈕嗎？
3. 這些狀態和視圖之間發生了哪些轉換？ 他們應該如何動畫化？

如果由您來為客戶端的並發生成 UI，請反過來執行相同的操作：使用線框工具並創建一套完整的屏幕佈局，包括視圖在不同應用程序狀態下顯示的任何變體。 這可能是一項詳盡而乏味的工作，但您不會後悔——它可以使您免於因一個具有重大影響的小誤解而重新編寫大量代碼和重新創建接口。 如果您正在創建一個雙重應用程序（例如，同時適用於 iPhone 和 iPad），請為兩者創建單獨的線框。

屏幕尺寸也很重要。 （在撰寫本文時）有三種尺寸的 iPhone 屏幕。 3.5 英寸和 4 英寸屏幕的單獨線框可能過多，但您可能必須製作它們； 在大多數情況下，您可以簡單地更改比例。

如果您的客戶為您提供圖形，請確保它們的尺寸正確且縱橫比正確； 變形任何具有文本或對象（如圓圈）的位圖都會引入扭曲。 如果它們不匹配，請告訴客戶以匹配的尺寸重新創建它們。 不要以為您可以將 3.5 英寸的初始屏幕拉伸成 4 英寸的初始屏幕並隨其滾動。

功能性

在應用程序設計文檔中要問的關鍵問題：

• 應用程序做什麼，它做的速度有多快？
• 什麼是可能的故障情況以及如何處理它們？
• 第一次執行時（即安裝後）做了哪些一次性操作？
• 如果用戶創建任何類型的條目（例如書籤），有什麼限制？

概括這些想法，並儘可能詳細和徹底——因為這裡的錯誤或誤解將意味著重寫代碼。

里程碑

您的規範模板應該佈局清晰的里程碑。 如果您的客戶編寫功能和用戶界面設計，您應該隨後就一組里程碑達成一致。 有時這些也是計費閾值，但至少它們提供了一個明確的完成指標。 里程碑可能是在功能和/或組件方面； 如果演出涉及一套可交付成果，它們甚至可能是單獨的應用程序。 如果可能，里程碑的持續時間應該大致相等。

軟件設計規範示例

在這裡，我將佈置一個適當的設計文檔的示例結構。 當然，這個模板應該根據需要進行調整。 對於另一個示例，請參閱 Joel Spolsky 基於此文章的示例規範。 他處理文件的方式略有不同，但有著相似的情緒。

目標聲明

包括一個描述項目及其目標受眾的簡短段落。

功能說明

應用程序做什麼？ 用戶會遇到哪些應用狀態（核心用戶場景的高級描述）？

例如，您的功能描述可能如下所示：

• 第一次運行
• 創建一個新的_____（遊戲、搜索等）
• 運營
• 背景和前景行為

用戶界面

包括每個頁面的線框，詳細說明：

• 每個控件，包括狀態（啟用/禁用/突出顯示）和操作。
• 支持它們之間的方向和過渡。
• 代表的功能。
• 錯誤處理。
• 尺寸和約束。

以下是與我最新的 iOS 應用 NotifEye 相關的線框圖：

如果你有興趣，我使用 Balsamiq 的線框圖工具製作了這些模型。

例如，您的 UI 描述可能如下所示：

• 導航欄
  • 左側導航控件：返回首頁
  • 標題欄：當前畫面或操作名稱
  • 新建按鈕：創建一個新事物
• 表視圖
  • 第 0 節：節標題
  • 第 0 行：
    • 行控制 0（例如，圖像）
    • 文本行 0
    • 文本行 2

里程碑

如上所述，完成期限和預期可交付成果。

例如，設計文檔模板中的里程碑部分可能如下所示：

1. 外觀應用程序顯示屏幕並帶有臨時過渡和示例圖像/文本
2. 通信協議：應用程序連接到網絡/服務器
3. 功能里程碑 1：……
4. Alpha 應用程序（具有完整功能）
5. 穩定
6. 發布

確保軟件文檔保持相關性

我並不是說一旦您和您的客戶就規範文件達成一致，設計階段就結束了。 總會有你們沒有考慮過的細節，你和客戶都會在看中間結果的同時，遇到新的想法、設計的變化、意想不到的設計缺陷和不可行的建議。

設計將不斷發展，並且應在文檔中捕獲更改。 在我 25 年的經驗中，我從來沒有參與過這樣的項目——其中包括我自己的應用程序（即，我是我自己的客戶）。 即便如此，我還是創建了一個包含詳細規格的設計文檔，並根據需要進行了調整。

最重要的是，保持聯繫。 每周至少幾次，聯繫你的客戶，報告你的進展，要求澄清，並確保你們有相同的願景。 作為您溝通的試金石，請嘗試確保您和您的客戶對以下三個問題給出相同的答案：

1. 開發人員剛剛在做什麼？
2. 開發商目前在做什麼？
3. 開發者接下來會做什麼？