ドキュメントライティング 6 文書作成のルール

作成日時：2025-08-11
更新日時：2025-08-13

文書作成におけるルールを数例記載する。
4 コーディング原則を使うと重複するものは除外した。

6.1 「何故」を書く

文書には「何故」を書く。
何をするかしか書いていない要件定義書。
どうするかしか書いていない設計書。

何をしているか、何をするかは現場を見れば分かるが、
「何故そうしたか」はその時点でどこかに残さなければ、高確率で情報がロストする。
いつまでも同じ人間がプロジェクトに居続けるわけでは無いし、人間は忘れる生き物である。

提案系の書類に「何故」を書く。
それは提案の根拠や、説得力となるから。

設計書に「何故」を書く。
それは設計の理解を促すから。
それは設計の変更容易性をもたらすから。
それはTDD(テスト駆動開発)のように、変更する勇気をもたらすから。

ADR(Architecture Decision Record)を書く。
それはシステムにおける思想を知る良い資料になるから。
それは変更容易性をもたらすから。
adr-toolsというのがあるらしい

主観的な表現に過ぎないため。
ここにおける感情とは、形容詞や副詞、感嘆符、疑問符、その他感想文である。
汚い言葉も使わない。(驚き最小の原則、バイアス)

数字を使用して具体的に記述する。

「これ」「それ」「あれ」「どれ」と記述しても、読み手が同じものを頭に浮かべるとは限らない。
曖昧さを生み出すので極力使わない。

例えば、以下のような文章は読みづらい。

A「今日の進捗を教えて」
B「今日は進捗を先程のチケットで試験の確認と終わりましたから、別に案件がチケットは今日が定時までには終わる予定。」

文章の意図が曖昧になる。
「来週デプロイする」「さっき修正した」
誰が何をするのか。いつ何を直したのか。
読み手と書き手が頭に浮かべたものが同一であると保証できない。

形容詞と感想を排除し、数字を使って具体的に表現する。

言い切りや断定を使う。
ただし、その前後には根拠が必須となる。

冗長なため。

伝えるためならば手段は選ばない。
図を使用したほうが明確に意図を伝えらえるならば、それを使用する。

読み手に疑問を発生させてはいけない。
疑問の回答はすべて文書中に存在していること。

見出しやトピック・センテンスは問題提起をさせる役割を持つので、
それにより疑問が発生するのは問題ない。
ただし、本文やサブ・センテンスでその疑問に対する回答や、主張の根拠が提示されていなければならない。