原文連結：エンジニア歴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 日補充）

關於「每行字數〜」、「縮短句子」和「使用條列式」，已重新審視表達方式，主要內容將保持不變。