原文連結：エンジニア歴20数年の私が、設計書を書く際に心がけていること - Qiita
上一篇主要介紹「需求定義到內部設計」的流程，接下來這篇文章，將著重於設計規格書的寫法。
先是從作者個人角度統整觀點，如何提升文件的易讀性，以及如何避免資訊混淆等；而在團隊開發中，如何制定一致的「規格書撰寫方式」，使其易於後續維護。
以下正文開始。
前言
時間過得真快，轉眼間我已經在 IT 行業度過了四分之一個世紀。
在這段時間裡，我寫過大量的「設計文件（規格書）」，但內心仍充滿困惑和迷惘。
儘管如此，俗話說「亀の甲より年（薑是老的辣）」，我試著從「個人」和「團隊」兩種角度總結出經驗法則。
- 本文的主題是「針對設計規格書，開發文件的撰寫方式」
- 本文假定的規格書，是以 Excel 或 Word 撰寫成正式的（≒ 交付物）設計文件。
- 因此，比起以自家服務開發或敏捷開發為前提，委託開發、瀑布式開發可能更適合本文內容。
＜請注意＞
本文內容是作者個人見解，並不代表所屬公司的立場、策略、意見。
個人所注意的事情
在文章開頭說明該文件的建立目的和定位
- 例如「本書將描述 ◯◯ 功能中 ×× 畫面的佈局設計以及輸入輸出設計」。
- 若有相關文件，可以寫上「關於 △△，請參考 □□」。
- 特別適用於設計階段之後（例如系統測試、維護或新增功能時），「搜尋」設計文件的情況。
首先考慮章節架構
- 考慮章節架構，也可以說是設計一份設計文件。
- 如果可以，最好在只寫出章節標題的狀態，給合適的人過目，如此可以降低基本認知差異的風險。
先顯示整體 → 再解釋細節
- 這不僅適用於設計文件和發表文稿，任何文件檔也同樣適用。
注意每行的字數
- 有些人會在 A4 橫向格式中，寫很長的文句，但這將導致閱讀困難。
- 每行最佳文字數
- 如果用 Google 搜尋，可以發現許多網站文章，對橫向書寫的建議是每行 30〜35 個字。
- 以我來看，設計文件最多不超過 40 個字，這是為了易讀性和每頁資訊量之間的平衡。
- 40 個字並沒有明確的根據，但如果是「一行 80 字節」，可能會讓人有所感觸⋯⋯
- 字數可以根據個人的基準來決定，重點是「需要注意每行文字」這一點。
縮短句子
- 長句子往往形成複雜的結構，容易產生誤解。
- 個人建議以「每句不超過兩行（即 80 個字符以內）」為目標。對於跨越三行的句子，應該考慮是否能進行拆解。
使用條列式
- 列舉項目的長句，通常可以轉換為條列式。
- 在分解結構複雜的句子時，條列式通常非常有效。
使用圖表
- 比起文字，人類更容易透過圖表直觀理解。
- 特別是在表現整體概念時，圖表比文字更有說服力。
使用表格
- 這對預防損害方面非常重要。
- 若試圖只用文字描述複雜的情況，可能導致讀者產生誤解。
使用縮排（Indentation）
- 縮排是一種有效的方式，可以讓讀者在視覺上理解文章結構。
統一主語
- 「當 ◯◯ 按鈕被點擊時，將顯示 ×× 畫面」和「當點擊 ◯◯ 按鈕時，×× 畫面將被顯示」的主語是不同的。
- 在設計文件中，通常主語是「系統」或「用戶」。雖然沒有必要堅持哪一種，但至少在文件中要保持一致。
- 順帶一提，我在設計文件中傾向於使用「系統」作為主語。
統一用詞
- 對於相同功能、相同概念，應該使用完全相同的詞彙，不要用不同的詞彙來描述同一件事。
- 例：「日締め」、「日次締め」、「日締処理」（代表截止日期）
- 這些看似小事，但在系統開發中，團隊成員之間微小的認知差異，往往會引發大問題。
- 在專案中建立詞彙表。
- 對於縮寫也要在詞彙表中記錄，或在文件開頭寫上「Ruby on Rails（以下簡稱 RoR）」等內容。（除非是已經廣泛使用的縮寫，如「IT」等）
不要創造新詞
- 常見例子是與日期相關的詞。
- 「執行日期」、「處理日期」、「當日」⋯⋯
- 是從哪裡取得？包含時刻嗎？時區是什麼？是否有曆法差異？
- 「執行日期」、「處理日期」、「當日」⋯⋯
- 如果是專案內共享的概念，請在詞彙表中記錄定義。
- 如果是在該文件內，獨自建立的詞語，應該建立該詞語的定義項目，並明確做記錄。
排除寫法不一致
例如：
- 「サーバ」和「サーバー」：統一拼音
- 「Web」和「ウェブ」：名詞統一使用中、英或日文表示
- 「4月」、「４月」和「四月」：數字統一用半形、全形或中文表示
- 「です・ます」和「だ・である」：句尾型態統一
如果是自己專用的筆記，可能不太需要在意這些細節。
但我認為，考慮有讀者存在，以「也許會有人根據這些細節來評價文件的好壞」為前提會比較保險。
專有名詞必須準確
- 例如「JAVA」是錯誤寫法，正確是「Java」。
- 對於產品名稱或公司名稱，容易出現混淆的情況，應該仔細查證，確保文字大小寫、單詞間有無空格等內容。
在領導團隊時所注意的事情
我認為，影響設計文件好壞的因素，比起個人的努力和心態，團隊之間的協力更為重要。
如果整個團隊在撰寫設計文件時沒有統一感，對於外部觀察者而言，設計文件的整體價值將會降低。
確認記錄的細節
- 對於基本設計文件和詳細設計文件，應該要記錄什麼，以及寫到什麼程度。
- 如果寫得過於詳細，將難以進行維護，最終導致沒有人會查看設計文件。
確認章節的記錄方式
這裡提供一個範例：
１．ｘｘｘ
１．１．ｘｘｘ
１．１．１．ｘｘｘ
（１）ｘｘｘ無論是使用全形/半形文字，以及是否使用縮排等細節，都需要仔細確認，這將有助於文件的統一性。
在量產規格書之前先製作樣本
- 最好由設計文件的審查者，也就是工程師來製作樣本。
- 樣本完成後，除了說「請看一下」以外，最好有一個場合，能夠向所有人解釋希望如何編寫樣本，以及樣本創作者的想法。
模板盡可能簡單
- 過多的規則將會降低生產效率。
- 過度拘泥於模板，將會使內容變得膚淺。在某些情況下，自由格式可能更適合表達。
- 確實格式也是品質的一部分，但製作一個平衡的模板更為重要。
確定如何保留變更歷史紀錄
- 紅→藍→綠→⋯⋯，有些成員可能會在每次進行變更時，把顏色變得很繽紛。
- 對此可能會有其他成員抱怨「難以閱讀！」（就是我）。
- 雖然從 Excel 轉移到 Markdown 等格式，將其納入版本控制系統可能會更好⋯⋯（有時也涉及到政治因素），但可能很難實現。
- 建立變更歷史紀錄表，並記錄在哪個表的哪個部分，進行了什麼修改，可能是現實的解決方案。
將上述事項整理成指南
- 使審查更加順利
- 當成員更換時，能夠順利進行說明
- 無論有多忙碌，都不應忽視指南的維護
總結
- 為了提高書寫能力，只有透過訓練。
- 最重要的是，身邊有人能夠嚴格指導並提供建議。
最後，如果這篇文章有任何不足之處，請在評論等地方告訴我！
（2018 年 2 月 15 日補充）
非常感謝得到許多反饋。
這篇文章僅基於我個人的經驗，可能存在思慮不足之處，也希望能夠根據各位的開發需求進行修改與應用。
我認為，透過教育和指導，可以在團隊內制定一致的「設計規格書撰寫方式」，從而在設計審查中更專注於「設計本身」。
（2018 年 3 月 11 日補充）
關於「每行字數〜」、「縮短句子」和「使用條列式」，已重新審視表達方式，主要內容將保持不變。
15th鐵人賽目錄傳送門：https://ithelp.ithome.com.tw/users/20135558/ironman/6290