ドキュメントライティング 5 型を使う

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

PHPにLaravel、JavaにSpringを使用するが如く。
明確な文書を作成するために型(フレームワーク)を使用する。
いくつかの型を紹介する。

※注意
厳密には文書作成のフレームワークではなく、思考のフレームワークである。
文書作成の際に使えるため、便宜的に文書作成のフレームワークと表記する。

5.1 BOSCAR

観点を整理したい時に使用する。
読み方は「ボスカー」。
下記のプロセスの頭文字をまとめたものである。

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

これに従って文書をまとめていく。
私は作業指示を出すとき/受けるとき、または要件定義をするときに使用する。

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

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

何が理由で、何をどのように行うかが整理される。
的確な観点の整理は不確実性と曖昧さを減らし、認知負荷を軽減する。

背景の重要性

背景が一番重要である。
背景(B)が伝達されない、または曖昧である場合、OSCARの妥当性を検証できない。
背景はモレなく、ダブりなく記述しなければならない。

作業指示

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

作業指示を受ける(読む)場合、その作業指示に背景が含まれているかを確認する。
無ければ聞く。無い場合、不確実性と曖昧さを有している。

要件定義

決して背景を曖昧にしてはならない。
このコンテキストにおける背景とは、顧客の要求の背景である。
つまり超上流工程の話で、「なぜ、顧客がシステム開発を発注したか」という根源的な情報である。

これが曖昧な場合、出来上がるシステムは顧客の要望を満たさない可能性が高い。
顧客が抱いている問題点を解消できなければ、システム開発は失敗と言ってよい。

5.2 PREP / SDS / CRF

3 結論を先に述べるを参照。

5.3 STAR

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

下記のプロセスの頭文字をまとめたものである。

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

以下は例。

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

5.4 5W2H

文書を具体的にするため、下記の要素を含める。

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

5.5 SBI/SBIIモデル

フィードバック時に使用。
下記のプロセスの頭文字をまとめたものである。

• Situation(状況)
• Behavior(行動)
• Impact(影響)

SBIIモデルはさらにIntent(意図)が追加される。

「Aという状況で起こしたBという行動はCという影響を与えた。」
相手に対し、具体的にフィードバックが出来る。
Intentがあれば、「何故そう行動したか」を元に改善のアドバイスが出来る。

5.6 独自フレームワーク

自身の中に何かしらの型がある場合は、それを使用する。

名前があれば記憶と整理が可能になるので、名前を付けたほうが良い。
脳内にハッシュインデックスを張るようなものである。

以下は私が自作したフレームワークである。

5.6.1 SPReaD

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

PREPとの違いは要点を記載する前に、全体の要約を提示すること、
別のフレームワークを柔軟に付け加えることができることである。

根底となる思想は下記である。

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

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

記載順と概要は下記である。

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

「まず、何なのか」の精神。
それが伝わるかどうかが、読み手の認知負荷を左右する。

5.6.2 PREP/C++

PREPに対しCounter(反論)を加え、そのCounterに対し更にCounterを加える。
メリットしか記載されていない文章は説得力に欠けるため。
デメリットも記載し、それをどう克服できるかを具体的に説明する。

5.7 その他の概念

特定文書類型の作成指針。

5.7.1 内部向け障害報告

下記の観点を盛り込む。

• 事象(5W2H)
• 原因
• 対応
• 再発防止策

5.7.2 手順書

操作⇒結果となるように記述する。
「◯◯する⇒◯◯という状態になる」のように。

次へ