良いドキュメントの３つの要素

良いュメントがなぜ必要か

ドキュメントを通じて、書き手と読み手の双方の目的を達成することができるため

三つの要素

• Effectiveness

  • 必要な情報を正しく得られる。書き手が伝えたいことが読み手に伝わる工夫が必要
  • 以下の工夫を行う
    • 曖昧さを廃して、明確な文章で書く
    • できるだけ具体的に書く
    • 誤解なくよめる文章で書く

• Satisfaction

  不快さがなくポジティブに受け止められる。ドキュメントを効率的に伝えたい場合は、読み手の心情も考慮する必要がある。

  ポジティブに伝えるために、以下の工夫をする

  • 肯定的で書く

    🙅‍♂️100件を超えるデータを登録することができません

    🙆‍♂️100件までデータを登録することができます

    しかし、強く主張したい時にはあえて否定的に書くこともある

    Ex：電源を切らないでください

  • 信頼される表現で書く

• Efficiency

  効率よく理解ができること。研究結果より、読み手はほとんどドキュメントを最後まで読まない。そのため、流し読みされる前提で必要な情報を伝わるように書く努力が必要。

  そのため、以下の工夫をする

  • 要点を先に伝える
  • どこになにが書いているかをわかりやすくする
  • 話の流れを整理し、理解しやすくする
  • 簡潔で読みやすい文章で書く
  • 必要な情報だけを書く

ドキュメント作成の5つのステップ

1. 読み手とテーマを選定する

誰に何を伝えるのかを目的とする。

• 読み手：誰に対してのドキュメントか

  • 読み手を理解する。読み手を理解するためのポイントは、次の３つ
    • 読み手の知識レベルを理解する
      • エンジニアが関わるドキュメントでは以下に分類する
        • プロダクトの関する知識
        • 技術に関する知識
        • 業務に関する知識
          • Ex:
            • プロダクトの関する知識：初心者
            • 技術に関する知識：上級者
            • 業務に関する知識：初心者
    • 読み手の目的を理解する。できるだけ具体的にする。
      • Ex：
        • 🙅プロダクトの使い方を知りたい
        • 🙆導入の方法を知りたい・機能の使い方を知りたい・エラーへの対処方法を知りたい・アップデートでの変更点を知りたい。
    • 読み手の立場や役割を理解する
  • 読み手に必要な情報は関係者にヒアリングすること

  Ex: プロダクトのマニュアルの読み手を絞り込む

  切り口	絞り込みの例
  読み手の知識レベル	- 初心者向け

  • 上級者向け | | 読み手の目的 | - プロダクトの導入手順を知りたい
  • トラブルの解決方法を知りたい | | 読み手の立場や役割 | - システム管理者
  • 事務担当者
  • 一般ユーザー |

• テーマ：何に対してのドキュメントか

  上記の読み手を絞り込めるとテーマも絞り込みやすくなる

  改善前：

  • プロダクトのユーザーに、プロダクトの使い方を伝える

  改善後：

  • プロダクトを導入したい、初心者のシステム管理者にプロダクトに導入手順を伝える
  • プロダクトの利用中にエラーを遭遇したユーザーに、エラーの原因と対照方法を伝える

2. テーマを分解する

• 上記のテーマをサブテーマ（なぜ・何を・どうやって）に分解する。

  • なぜ（Why）：なぜその企画が必要なのか
  • 何を（What）：何を実現したいのか
  • どうやって（How)：どうやってそれを実現するのか

• テーマの分解は具体例か構成要素かのいずれで分解する

  • 構成要素：仕様書のドキュメントの場合は、機能単位
    • プロダクトの機能を説明する
  • 具体例：マニュアルの場合、利用目的の具体例

3. ドキュメントの構成を組む

テーマを分割後、見出しの構成を組む。見出しは本文の内容をできるだけ具体的に表した見出しにをつけるか

• 本分に何が書かれているか
• 本文で何がいいたいか