X(Twitter) Zenn GitHub RSS 共有

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

作成日時：2024-03-16
更新日時：2024-08-01

1 概要

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

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

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

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

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

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

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

2.1 DRY原則

Don’t repeat yourself - Wikipedia

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

2.2 KISS原則 / 小は美なり

KISSの原則 - Wikipedia

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

2.3 YAGNI原則 / SRP

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

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

2.4 SLAP

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

2.5 PIE原則

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

2.6 名前重要

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

※シノニム：
同義語。1つの実態に複数の名前が付いた状態。
例えば、受注番号と発注番号という名称がどちらも伝票番号の事を指している状態。

※ホモニム：
同音語。1つの名前に複数の実態が付いた状態。
例えば、伝票番号という名称が受注番号と発注番号の事を指している状態。

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では下記の拡張機能がある。

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

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

下記は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 テストを行う

3.9 テスト駆動開発

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

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

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

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

4.1 BOSCAR

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

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

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

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

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

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

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

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

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

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

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

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

4.2 PREP / SDS / CRF

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

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

PREP

SDS

CRF

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

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

4.3 STAR

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

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

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

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

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

4.4 5W2H

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

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 内部向け障害報告

4.8 手順書

4.9 SBIモデル

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

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

5 文書作成のルール

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

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

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

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

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

5.4 指示語は極力使わない

5.5 助詞を適切に使う

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

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

5.6 「何故」を書け

「何故」を書け。

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原則違反による強調効果

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

6 参考情報

6.1 書籍

6.2 リンク