ドキュメントライティング 4 コーディング原則を使う

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

コーディング原則を使用すれば、読みやすい文章を書ける。

アナロジー思考である。
プログラミングとは「プログラミング言語を使用した命令の記述」。
ドキュメントライティングとは「自然言語(日本語)を使用した文章の記述」。
どちらも言語を使って記述をしている。

プログラミングにおいて、コーディング原則を順守すると可読性に優れたコードが書けるというならば、
ドキュメントライティングにおいても、その恩恵を受けられるはずである。

事実、ドキュメントライティングの本を読んでいると、コーディング原則との類似点を見かける。
その逆も然りである。

以下に、コーディング原則をドキュメントライティングに適用する例を記載する。

4.1 DRY原則

同じ情報を複数回記述してはいけない。
なぜならば、文量が増えれば増えるほど可読性は下がるため。

ただし「わざと反復して強調する」という意図があるならば許容する。
PREPフレームワークなどがこれにあたる。

4.2 KISS原則 / 小は美なり

シンプルで簡潔な文章にする。
なぜならば、難解な文章は認知負荷を上げるため。

500行のメソッドや、10,000行のクラスは読みづらい。
同様に一文の文字数が多い文章は読みづらい。

4.2.1 出来る限り一文は短くする

長い文章を書かない。
コーディングにおける80文字ルールのように、一文の文字数の上限を設ける。
短い文章を書くとプラスの作用がある。

1つは読点を増加させない作用である。
長い文は意味を区切るために読点を打つ必要があるが、これが過剰になると可読性を下げる。
短い文章にはそれが無い。
読点が多い場合、一文における文字数が過剰であるサインとも言える。

もう1つは主題と述語を近づける作用である。
「私は、(任意の500文字の文章)、XXXだ。」という文章は可読性が低い。
過剰な複文で構成され、被修飾部を見誤ったりする。
短い文章にはそれが無い。
主述のねじれも防げる。

箇条書き

同一の主格に対する説明が連続する場合やチェックリストには、箇条書きを使用してよい。
ただし、並べる項目はなるべく少なくする。
なぜならば、人間が短期記憶に保持できる数は7±2個であるため。
(参考:ミラーの法則、マジカルナンバー7)

4.2.2 難しい表現、単語を使わない

認知負荷が上がるため。
難しい表現、単語を使う場合は別途、説明を記述する。
読み手が理解できるならば使ってもよいし、むしろ使うほうが可読性を下げる。
(参考:圧倒的読み手意識)

外来語表記法

「Thank you」は「サンキュー」と表記できるが、「Thank you」の意味を理解していないと「サンキュー」が何を表しているか理解できない。
横文字は解説を記載するか、日本語にあたる用語を使用する。

4.2.3 漢字をひらく

あえて漢字をひらがなで表記してで読みやすい文章にする手法。
漢字を過剰に使用すると可読性を下げる。

4.3 YAGNI原則

その文書、見出し、段落に関係のない内容は一切書いてはならない。
読み手はいきなり現れた無関係の情報に驚いたり、無関係な情報を関係があると思い記憶し続ける。
結果、認知負荷が上がる。
(参考:驚き最小の原則)

ただし、アイスブレイクやコラム等、何らかの目的がある場合はその限りでない。

4.4 単一責任の原則

1つの構造は1つの内容のみに関して記述しなければならない、
文書、章・節、段落、文。
全てが単一の内容でなければならない。
例えば、このセクションは「単一責任の原則」に関する内容以外は書いていない。

また、1つの文は複数の捉え方があってはならない。

4.5 SLAP

記載している内容のレベルを揃える。
文章量が他の同一階層の見出しに比べて多い場合は、別セクション/別見出しに切り出す。
メソッド抽出によるリファクタリングと同一。

4.6 PIE原則

意図的、かつ表現豊かに文章を記述する。
意図を明確に伝えることが、最重要事項であると認識する。
2 思想に記載した内容そのものである。

圧倒的読み手意識で文章を推敲する。

• 本当に読みやすいか
• 読み手のレベルに合わせた表現となっているか
• 誰に向けての文書なのか
• 読み手がどのような状態になって欲しいのか

4.7 名前重要

文書に存在する名前、つまり見出しや用語は適切なものを使用しなければならない。
コーディングにおけるクラス、メソッド、変数の命名と同じである。

4.7.1 見出し

見出しは、読めばそのセクションの内容を把握出来るようにする。
かつ、セクションの内容と矛盾してはいけない。

上記が守られた場合、その文書は見出しだけで内容を把握できるため認知負荷が下がる。
既知の情報に関しては読み飛ばすことができるため。

適切な見出しは3 結論を先に述べると同じ効能がある。

4.7.2 用語

ホモニム、シノニム、表記揺れ、誤字脱字は認識齟齬を発生させるため、排除する。
また、読み手に合わせた適切な用語を選択する。
読み手がその用語を理解できないならば、用語の説明を近くに記載するか、用語を使わずに記述する。

ホモニム

同音語。1つの名前に複数の実態が付いた状態。
同じ名称で異なる意味を持つ言葉。
文脈によって意味が変わる言葉。
「出荷」は顧客への商品配送か、別拠点への移送なのか。

シノニム

同義語。1つの実態に複数の名前が付いた状態。
異なる名称だが同じ意味を指す言葉。
「得意先」と「納入先」

4.8 深いネストを作らない

深いネストのコードが読みづらいのと同じで、見出しの階層が深すぎる文章も読みづらい。
箇条書きもまた、同様のケースになりやすい。
階層は3階層ほどに留める。

ネストが深くなる場合、その段落/章が見出し以上の内容を記述している可能性がある(単一責任の原則/SLAP違反)。
上位階層に別セクションとして移動する。
コーディングにおけるメソッド抽出と同じ。

行数の多いコードとネストが深いコードでは、後者のほうが認知負荷は高くなる。

4.9 読点は意味の切れ目に打つ

読点が適切に打たれていない文章は読みづらいし、誤読を誘発する。
メソッドチェーンへ適切に改行を入れるように、文章の意味の切れ目に読点を打つ。

以下、コーディングに置き換えたイメージ。

// 読点(改行)なしは読みづらい
var newList = list.stream().filter(str -> str.startsWith("A")).collect(Collectors.toList());

// 適切な読点(改行)を打つ
var newList = list.stream()
    .filter(str -> str.startsWith("A"))
    .collect(Collectors.toList());

// 一文を短くする(読点を消す)
var newList = filterStartingWithA(list);

4.10 Linter/Formatterの使用

コーディングでLinter/Formatterを使っているのだから、ドキュメントライティングでも使うべきである。
VS Codeでは下記の拡張機能がある。

• Markdown All in One
• markdownlint
• vscode-textlint
• テキスト校正くん
• Code Spell Checker

4.11 クラス設計をするが如く記述する

ドキュメント設計はクラス設計と同じである。
伝えたい事(クラス)をポイント(メソッド)ごとに分割し、構造的に記述していく。
プラグラムの構成要素をドキュメントに置き換えると下記のようになる。

• 「文書」はクラス
• 「序文/概要」はクラスのxDocコメント
• 「章」はメソッド
• 「段落」はブロック
• 「行」はステートメント

下記はPREPフレームワークを使用した提案文書をクラスに置き換えてみたもの。
※一部省略。

/**
 * 概要：○○に関する提案
 */
public class 提案内容 {

    public void 目次() {
        結論();
        理由();
        具体例();
        結論();
    }

    private void 理由() {
        理由詳細1();
        理由詳細2();
        理由詳細3();
    }

    private void 理由詳細1() {

        // 提案理由の詳細
        System.out.println("◯◯である。");
        System.out.println("◯◯である。");

        // 反対意見に対する対応
        System.out.println("一方、こういう意見もある。");
        System.out.println("それに対してはこうする。");
    }
}

4.12 表現の統一

• 「ですます調」と「である調」はどちらかに統一する。
• 用語は統一させる。シノニム・ホモニム・表記ゆれは発生させてはならない。
• コーディング規約と同じく、文書内で書き方は統一させる。

4.13 二重否定の禁止

二重否定は認知負荷を上げる。
二重否定は認知負荷を「上げなくない」。

4.14 テストを行う

コーディングでテストを行うように、ドキュメントでもテストを行う。

4.14.1 Linterを使用した静的テスト

4.10で紹介したLinterを使用し、誤字脱字や表記ゆれのようなミスをなくす。

4.14.2 読む/読んでもらうという動的テスト

文書を書いたならば、自分で読み直して意図が通じるか、読みやすいかどうかを検証する。
しかし、自身が書いた文章であるため、推測可能性が高い状態となる。
その状態で読み直しても、適切な評価を下すことができない。
この場合は、数日置いてから読み直すか、他者やAIに読んでもらって検証する。

4.15 見た目の美しさ

見た目が美しいコードが読みやすいのと同様に、見た目が美しい文書は読みやすい。

インデントがバラバラなコードは読みやすいか。
タブとスペースが入り乱れたコードは読みやすいか。
改行が一切存在しないコードは読みやすいか。
記法が統一されていないコードは読みやすいか。
否、読みづらい。

改行が不適切な文章は読みやすいか。
読点が不適切な文章は読みやすいか。
段落のない文章は読みやすいか。
漢字が過剰に多く、見た目が黒い文章は読みやすいか。
否、読みづらい。

文豪はフォントや余白、ふりがな、句読点などといった、文章の視覚的要素にさえ気を配る。
(参考:谷崎潤一郎著.　文章読本)

見た目が汚い文書は読みづらい。
見た目が美しい文書は読みやすい。

次へ