[![hackmd-github-sync-badge](https://hackmd.io/5wlbEHQqR3iMLuSJh1XsfQ/badge)](https://hackmd.io/5wlbEHQqR3iMLuSJh1XsfQ) ###### tags: `2023鐵人賽` `qiita` `規格書` `設計文件` # [2023 15th鐵人賽] Day26 - 擁有 20 多年工程師經驗的我，在撰寫設計規格書時所注意的事情 > 原文連結：[エンジニア歴20数年の私が、設計書を書く際に心がけていること - Qiita](https://qiita.com/y-some/items/90651c1e27f7798f87c6) 上一篇主要介紹「需求定義到內部設計」的流程，接下來這篇文章，將著重於設計規格書的寫法。 先是從作者個人角度統整觀點，如何提升文件的易讀性，以及如何避免資訊混淆等；而在團隊開發中，如何制定一致的「規格書撰寫方式」，使其易於後續維護。 以下正文開始。 --- [toc] ## 前言 時間過得真快，轉眼間我已經在 IT 行業度過了四分之一個世紀。 在這段時間裡，我寫過大量的「設計文件（規格書）」，但內心仍充滿困惑和迷惘。 儘管如此，俗話說「[亀の甲より年（薑是老的辣）](http://kotowaza-allguide.com/ka/kamenokouyoritoshi.html)」，我試著從「個人」和「團隊」兩種角度總結出經驗法則。 - 本文的主題是「針對設計規格書，開發文件的撰寫方式」 - 本文假定的規格書，是以 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 日補充）** 關於「每行字數〜」、「縮短句子」和「使用條列式」，已重新審視表達方式，主要內容將保持不變。