ドキュメントライティング

作成日時：2024-03-16
更新日時：2024-09-29

1 概要

現時点(2024-03-16)における、ドキュメントライティングに関する考えをまとめた記事。

2 コーディング原則に基づく

コーディング原則はコーディングに限らず、他のさまざまな領域においても認知負荷(※)を軽減する効果がある。
という最近の私の思想。

参考：アナロジー思考
違う事柄のなかから双方の類似点を見つけて、解決策を見いだす思考。
類似点ではなく、一方的にコーディング原則を適用するわけだから、若干意味は違う。

例えば、以下の分野にもコーディング原則を適用できると考えている。

• コミュニケーション
• ドキュメントライティング
• デザイン
• SQL

コーディング原則をドキュメントライティングに当てはめてみる。
コーディングにおける本来の意味はリンクを参照するか、ネットで検索すること。

※認知負荷：
人間が情報を処理する際に要求される精神的な努力のこと。
無駄に頭を使わされること。分かりづらいこと。

2.1 DRY原則

Don’t repeat yourself - Wikipedia

同じ情報を複数回記述してはいけない。

• 冗長かつ文書のボリュームを増やしてしまう。
• ただし「わざと反復することで強調する」という意図があるならば許容する。
  • 例えばPREPフレームワークなど(後述)

2.2 KISS原則 / 小は美なり

KISSの原則 - Wikipedia

シンプルで簡潔な文章であること。

• 難解な文章は認知負荷を上げる。
• 出来る限り一文は短くする。
  • 箇条書きの使用。
  • 長い文章を書かない。(100文字以内に収める)
  • 句点を増加させない作用がある
  • 主語と述語を近づける作用がある
• 難しい表現、単語を使わない。
  • 難しい単語を使う場合は別途、説明を記述する。
• 漢字を適度にひらく。
  • あえて漢字をひらがなで表記することで読みやすい文章にする手法のこと。
• 各セクション内の文章量も少なくする。

2.3 YAGNI原則 / SRP

YAGNI - Wikipedia
単一責任の原則 - Wikipedia

その文書、見出し、段落に関係のない余計なことは一切書いてはならない。

• 冗長かつ文書のボリュームを増やしてしまう。
• 本来、伝えたかった意図を隠してしまう可能性がある。
• ただしそれが読みやすさに繋がるのであれば入れるべき。
• 1つのものには1つの役割しか持たせてはいけない。(SRP)
  • 文書、段落、文。全てが単一の内容でなければならない。
• その文章の捉え方は1つだけでなければならない

2.4 SLAP

記載している内容のレベルを揃える。

• 文章量が他の同一階層の見出しに比べて多い場合は、別セクション/別見出しに切り出す。
  ⇒メソッド抽出によるリファクタリングと同じ。

2.5 PIE原則

意図を明確に伝えることが最重要事項であることを認識する。

• 読み手の立場になって読み返してみる。
  • 本当に読みやすいか。
  • 読み手のレベルに合わせた表現となっているか。
  • 誰に向けての文書なのか
  • 読み手がどのような状態になって欲しいのか
• 「読みやすさ」を重視する。
• 認知負荷を発生させてはいけない。
• 具体的に、具体的に。

2.6 名前重要

見出しは見ればそのセクションの内容を把握出来るような、適切な文言にする

• コーディングにおけるクラス、メソッド、変数の命名と同じ。
• セクションの内容は見出しと矛盾してはいけない。
  • ⇒(YAGNI原則 / SRP)
• 良きドキュメントは見出しだけ読めば内容を把握できる。
  • パラグラフライティング
• ホモニム、シノニム、表記揺れは認識齟齬を発生させるため、極力排除する。

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

※ホモニム：
同音語。1つの名前に複数の実態が付いた状態。
同じ名称で異なる意味を持つ言葉。
文脈によって意味が変わる言葉。
「出荷」→配送？移送？

厳密にはホモニムの定義に合っていないが、IT業界ではホモニムと扱われるらしい。
とにかく名前は明確に定義しろという話。

業務用語定義の重要性＜システムの調達＜Ｗｅｂ教材＜木暮仁

2.7 デメテルの法則

伝える情報は最小限に。

3 コーディング規約に基づく

コーディング規約もコーディング原則と同じく、他の領域において認知負荷を下げる効果があると思っている。

3.1 高凝集であること

1つのセクションは1つの意味のみについて記述すること。
⇒(YAGNI / SRP)

3.2 深いネストを作らない

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

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

3.3 読点は意味の切れ目に

メソッドチェーンへ適切に改行を入れるが如し。

読点が打たれていない文章は読みづらい。
読点の打ち方に正解は無いが、文章の意味の切れ目に読点を打っておけば、だいたい見やすくなる。

例えば、上の文章は3つの意味を有しており、そこで読点を打っている。

上記ルールは絶対ではなく、その読点が読みやすさに繋がるというのであれば、好きなだけ読点を打つと良い。
(⇒PIE原則)

かと言って、読点が多すぎる文章もまた読みづらい。
その場合は、一文を短くして読点を消す。
もしくは箇条書きにする。

以下、コーディングに置き換えた場合。

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

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

// 一文を短くする
var list2 = filterStartingWithA(list);

また、読点が多いのであればそれは別段落として抽出するサインである。
(メソッド抽出)

3.4 Linter/Formatterの使用

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

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

3.5 クラス設計をするが如く

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

• 「文書」はクラス
• 「序文/概要」はクラスの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("それに対してはこうする。");
    }
}

3.6 表現の統一

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

3.7 二重否定の禁止

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

3.8 テストを行う

• コーディングでもテスト/リファクタリングを行うように、ドキュメントにもテストを行う。
• Linterを使用した静的テスト
• 自分で読み直すという動的テスト
  • 文書を書いたら数日置いて見直せ
  • 推測可用性をわざと下げて、本当に読みやすいかテストする。
• 他者に読んでもらうことによってバグ(誤り)を検出するもよし。

3.9 テスト駆動開発

自分で読み直して(テスト)読みづらいならば直せ(リファクタリング)

4 文書作成のフレームワーク

PHPにLaravel、JavaにSpringを使用するが如く、文書作成でもフレームワークを使用する。
※厳密には文書作成のフレームワークではないけれども。

文書作成におけるフレームワークは多数あるが、その内、私がよく使用するものを紹介する。

4.1 BOSCAR

観点を整理したい時に使用する。

私は作業指示を出すとき/受けるとき、または要件定義をするときに使ったりする。
読み方はおそらく「ボスカー」。

末尾にDが追加された「BOSCARD」もあるが、ここではBOSCARについて説明する。

下記項目の頭文字を並べたものである。

• Background(背景)
• Objective(目的)
• Scope(範囲)
• Constraint(制約)
• Assumption(前提条件)
• Report(成果物)

これに従って文書をまとめていく。

例として、「商品一覧画面の検索が遅い」というクレームがユーザーから上がって来たので、作業者に作業指示をする場合。

- Background(背景)
    - 「商品一覧画面の検索が遅い」というクレームがユーザーから上がった。
- Objective(目的)
    - 検索速度の向上。
- Scope(範囲)
    - 商品一覧画面のみ。
- Constraint(制約)
    - X月X日までにリリース可能となる事。
    - 改善後のレスポンスタイムは0.5秒以内を目安とする。
- Assumption(前提条件)
    - DBのリソースには余裕がある。
- Report(成果物)
    - ソースと試験仕様書・試験結果(単体/結合/負荷/パフォーマンス)。

上記の要点を含めた文章を記載すればいい。

個人的には背景が一番重要であり、発生した全てを伝えるべき。推測が容易になる。
仮にObjectiveが間違っていても、背景から検知可能なので、一種のチェックサムとして機能する。

仮に「特定の検索条件を追加したときのみ遅い」という背景情報があれば、
作業者はそのカラムにインデックスを貼るだけで済む可能性がある。
背景情報を伝えない場合、作業者はSQL全体の確認をするため、工数がかかる。
無駄な修正をして、デグレを発生させる可能性も出てくる。

逆に自分が指示を受ける側である場合、その作業指示にはBOSCARが含まれているかを確認する。
無ければ聞く。無いと不確実性と曖昧さを有するから。

的確な観点の整理が不確実性と曖昧さを減らし、認知負荷を軽減する。

4.2 PREP / SDS / CRF

提案や意見を述べるときに使用する。

下記項目の頭文字を並べたものであり、これに従って文書を作成する。

PREP

• Point (結論)
• Reason (理由)
• Example (例)
• Point (結論)

SDS

• Summary (要点)
• Detail (詳細)
• Summary (要点)

CRF

• Conclusion (結論)
• Reason (理由)
• Fact (事実)

- 主張(Point / Summary)
    - これを◯◯した方がよい。
- 詳細(Detail / Reason / Example)
    - 何故ならば◯◯だからだ。
    - 例えば◯◯ということが起こりうる。
- 主張(Point / Summary)
    - だからこれを◯◯した方がよい。

先に結論を述べたうえで、理由や根拠を説明することにより、具体的かつ説得力のある文章を作ることができる。

4.3 STAR

状況説明をするときに使用する。

下記項目の頭文字を並べたものであり、これに従って文書を作成する。

• Situation (状況)
• Task (やらなければならないこと)
• Action (やったこと)
• Result (結果)

- Situation (状況)
    - システムに障害が発生し、業務に多大な支障が出ている
- Task (やらなければならないこと)
    - 原因を早急に特定し、システムを復旧させる必要がある
- Action (やったこと)
    - 各部門からメンバーを集め対応にあたらせた
        - システムログの徹底的な解析
        - ベンダーとの緊密な連携
        - ユーザーへの経過説明と対応
    - 障害の原因を特定し対処を行った
- Result (結果)
    - 発生から約6時間でシステムは復旧した

ある出来事や問題に対する対処を、状況から結果に至る一連の論理的な流れで整理・説明できる。

※もし障害報告書ならば、このような具体性に欠ける内容なのはありえないがサンプルなのでよし。

4.4 5W2H

下記項目の頭文字を並べたものであり、これに従って文書を作成する。

• When (いつ)
• Where (どこで)
• Who (だれが)
• What (なにを)
• Why (なぜ)
• How (どのように)
• How Much (いくらで)

4.5 SPReaD

要点を文書の先頭に全て詰めて、後から詳細を記述する手法。
spread「(情報を)展開する」と掛かっている。

ドキュメントライティングの本を読んでいると、だいたい下記の事が書いている。
また、自分自身も仕事で文書を読んでいると、下記のようなことを思ったりする。

• 何の話か分からないまま読む文書は分かりづらい
• 予想可能な文章は効率よく理解できる
• 結論が冒頭に無いと、書き手の主張したいことが掴みづらい
• 理由が無ければ説得力に欠ける

相手の脳みそに関連情報を全部ロードした上で説明できるから
推測可能性が高い。

1. Summary
   何の話なのかを1行で表す。
   メールの件名をつけるが如く。
2. Point / Reason
   話の結論とその根拠/理由を簡潔に書く。
3. Detail
   各種フレームワークを使用して記述する。

Summary
Point / Reason
...

Detail(BOSCAR / PREP / STAR etc.)

文書のタイトル(Summary)
概要(Point / Reason)
展開(Detail)

4.6 PREP/C++

PREPに対し、Counter(反論)を加える。
メリットしか伝えない人間の提案は、説得力に欠ける。
反論は説明しなければならない、ということで明示的にCをつけた。

4.7 内部向け障害報告

• 事象(5W2H)
• 原因
• 対応

4.8 手順書

• 操作⇒結果
  • ◯◯する⇒◯◯という状態になる

4.9 SBIモデル

フィードバック時に使用。

• Situation(状況)
• Behavior(行動)
• Impact(影響)
• Intent(意図)※SBII

Aという状況で起こしたBという行動はCという影響を与えた。どういう意図があったのか。

5 文書作成のルール

5.1 結論や要点を先に述べる

• 読み手の思考を効果的に導き、本質的な理解が促進される。
• 先に結論を述べれば、読み手は書き手の伝えたい意図を頭に置いたうえで、文書を読んでくれる。
• 文書の意図が早い段階で明確にならないと、読み手の認知負荷は増大する。最後まで読まないと分からない文章はよくない。
• 見出しに「DBに関して」と書いておけば、読み手は脳内メモリにDBに関する情報をロードしてから文書を読んでくれる。
• 逆に書いていなければ、読み手は文書全体を読んだ後でようやく文書の意図がわかり、無駄な認知的リソースを消費することになる。
• 要点を書けないならば、それは内容を自分自身が理解していない証左。ちゃんと考える。

5.2 意図の単位で段落をまとめる

コードを書くとき、処理のまとまりごとに改行を入れるが如く、文章も意味のまとまりごとにまとめて段落とする。
まとまりが大きいのであるならば、それは別のセクションとして書くべし。
コーディングにおけるメソッド抽出と同じ。

5.3 形容詞/副詞と感想は極力排除する

• 形容詞/副詞と感想は曖昧性を生む。
  • これらは主観的な表現に過ぎないから。
• 具体的な数字に置き換えて記述する。
• ただし意図があるならば残してもよい。

A「この機能の実装にどれくらいかかるか教えて。」
↓
× B「かなりかかりそう。」
○ B「3日かかる。」

5.4 指示語は極力使わない

• 「これ」「それ」「あれ」「どれ」と記述しても、読み手が同じものを頭に浮かべるとは限らない。
• 曖昧さを生み出すので極力使わない。
• ただし確実に推測可能であるならば使用しても構わない。
  • スコープの狭い変数の名称を1文字にするが如く。

5.5 助詞を適切に使う

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

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

• 助詞は適切に使う。
• 同じ助詞は連続で使わない。
• 文を分割するか箇条書きにすれば、余計な助詞は消せる。
• 接続助詞は控える。文章が長くなるから。
  • 文を分割して、次の文を接続詞で始める。
• 格助詞10個（へ・や・の・と・から・を・に・が・で・より）
  • 「部屋の戸から鬼が出より」で覚える。

5.6 「何故」を書け

• 文書には「何故」を書け。 コーディングでコメントに「何故」を書くが如く。
• だいたいのドキュメントには何をするかしか書いていない。
  • 要件定義書は何をするかしか書いていない。
  • 設計書はどうするかしか書いていない。
• 「何故」が欠如している。
• 何をしているかは最悪ソースを見れば分かるが、「何故そうしたか」はその時点でどこかに残さなければ、高確率で情報がロストする。
  • いつまでも同じ人間がプロジェクトに居続けるわけでは無い
  • 人間は忘れる生き物である。

「何故」を書け。

• 提案系の書類に「何故」を書け。
  • それは提案の根拠や、説得力となるから。
• 設計書に「何故」を書け。
  • それは設計の理解を促すから。
  • それは設計の変更容易性をもたらすから。
  • それはTDD(テスト駆動開発)のように、変更する勇気をもたらすから。
• ADR(Architecture Decision Record)を書け。
  • それはシステムにおける思想を知る良い資料になるから。
  • それは変更容易性をもたらすから。
  • adr-toolsというのがあるらしい

5.7 主語と目的語を省略しない

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

5.8 主語と述語は近づける

• すぐに使わないのにメソッドの先頭に変数定義をしているソースと同じ。
• その変数に注意を払ってソースを読まなければならない。
• ドキュメントも同じく、使用する直前(述語の前)に主語を置く(変数定義)。

5.9 箇条書きは7要素まで

箇条書きは同格の列挙。(同一主語)
同格でない事象を列強するならば、それは段落わけして書く。

5.10 主題が何よりも重要である

何を伝えたいか、何を論じたいのか。
決してぶれてはならない。
⇒SRP原則。

5.11 読み手を考える

相手が容易に理解してくれるか、と何度も推敲を繰り返す。
⇒PIE原則。

5.12 トピックセンテンスを最初に書く

トピックセンテンスとは、そのパラグラフの概要を表した文章。
推測可能性が上がり、理解しやすくなる。
⇒SPReaD。
パラグラフとは文章の塊の事である。

5.13 主語と述語のねじれ

5.14 曖昧な表現はしてはならない

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

5.15 基本的に受け身で書かない

れる/られる、は使わない。
ただし主語に応じる。
能動態だと文章を短くできる。

5.16 驚き最小の原則

• メンタルモデル(その人の予測や考え方)を裏切らない
• 流れに沿って論述する
• 既知から未知へ
• いきなり別の話題や謎の用語を出してはいけない

5.17 root

下記のいずれかが記載されていないといけない。

• 根本原因
• 目的
• 理由
• ゴール(終了条件)

5.18 DRY原則違反による強調効果

意図的に繰り返すことにより、意図を明確にする。

• 似た言い回しの箇条書き(パラレリズム)
• SDS / PREP

6 参考情報

6.1 書籍

• 理科系の作文技術 -木下是雄 著｜新書｜中央公論新社
• プリンシプル オブ プログラミング
• リーダブルコード
• 理工系のためのよい文章の書き方

6.2 リンク

• 「公用文作成の考え方」について（建議） | 文化庁
• Google社のテクニカルライティングの基礎教育資料がとても良かったので紹介したい - Qiita
• Overview of technical writing courses  |  Technical Writing  |  Google for Developers
• エンジニアのための、いますぐ使える文章校正テクニック - ICS MEDIA
• エンジニアのためのドキュメント力基礎講座 - Speaker Deck
• エンジニア歴20数年の私が、設計書を書く際に心がけていること - Qiita
• ドキュメント作成スキル向上を目指す人向けおすすめ記事まとめ #新人プログラマ応援 - Qiita
• ハイライト | Google開発者向けドキュメントのスタイル ガイド | 開発者向け Google
• 仕様書の書き方 #新人プログラマ応援 - Qiita
• 社内で行ったビジネスライティング講座資料を公開します | DevelopersIO
• 誰がどう見てもそうとしか受け取れない文書術（公開版） - Speaker Deck