ドキュメントの書き方

方法論
Author

Ryo Nakagami

Published

2025-05-30

この記事のスコープ
  • ドキュメントを書くにあたっての基本ルールの紹介
想定知識

ドキュメントに何を書くか？(What)

ドキュメントとは「ある情報を、ある対象に伝える」ための手段です．ドキュメントを書くにあたって事前に

  • 「誰に」対して
  • 「何を」伝えるか

を明確化し，その目的に応じて構成や表現を設計することが重要です．

Example 1 : ドキュメント種類別の読み手と目的整理表

ドキュメント種類 誰に 何を
企画書 経営層・チームマネジャー・開発メンバー PJの目的・スコープ・予算・スケジュール
要件定義書 エンジニア システムの機能要件・非機能要件
基本設計書 エンジニア システムの動作仕様・インターフェース仕様
詳細設計 エンジニア ソフトウェアの内部構造・モジュール感のインターフェース・データ構造
テスト仕様書 プロダクトマネジャー・エンジニア テスト項目・テストデータ・テスト結果
ユーザーマニュアル ユーザー 機能の説明・利用目的・操作方法
管理・保守マニュアル システム管理者 管理や保守に関する機能の説明・利用目的・操作方法
リリースノート ユーザー・システム管理者 プロダクトのアップデートに伴う変更点

読み手の定義

ルール

「誰に」対してを特定する際，以下の３つを明確化することが有用です：

  1. 読み手の目的・ニーズ
  2. 読み手の知識レベル
  3. 読み手の立場

説明

目的が違えば、必要な情報・深さ・順序が変わる

  • 意思決定者 → 意思決定や承認に足る根拠がほしい → 結論とインパクト重視
  • 現場担当者 → どう使うか／どう実装するかの具体的な手順を知りたい → 詳細手順や実装方法が重要

知識レベルが違えば 説明の粒度・用語の選び方・例の使い方が変わる

  • 初心者 → 用語の定義や背景から丁寧に
  • 専門家 → 論点にフォーカスし冗長さを排除

同じ事実でも、立場によって関心ポイントが異なる

  • 営業 → 顧客影響やKPIに注目
  • エンジニア → 技術的妥当性や仕組みが重要

例: ユーザーマニュアルと開発者マニュアルのアウトラインの差異

種類 アウトライン構成方針 例
ユーザーマニュアル ユーザーが操作する順番 初期設定 → ログイン → 基本操作 → 応用操作 → トラブル対応
開発者マニュアル 開発者が開発する順番 環境構築 → モジュール設計 → API定義 → データ構造 → エラーハンドリング

アンチパターンと改善例

アンチパターン: 読み手の定義がぼやけている
  • プロダクトのユーザーに，プロダクトの使い方を伝える
改善例:
  • プロダクトを新規導入するシステム管理者に，プロダクトの導入手順を伝える
  • プロダクトの利用中にエラーに遭遇したユーザーに，エラーの原因と対処方法を伝える

どのようにドキュメントを書くか？(How)

良いドキュメントを書くためには、次の３点を押さえる必要があります：

  • Effectiveness; 必要な情報を正しく伝えられる, 合目的的であること
  • Efficiency: 効率よく内容が理解できる, readability
  • Satisfaction: 読み手に対する配慮があること

Effectiveness

説明

  • 書き表された情報が読み手に一意に伝わること
  • 書き表された情報がドキュメントの目的と合致していること

アクション

Efficiency

説明

  • 効率よく内容が理解できること
  • 読み手は流し読みする傾向があるので，流し読みでも情報が伝わるように構成立てること

アクション

    • ドキュメントを書く前に事前にアウトライン設計（どこに何を書くのか）
    • 文章ブロックに対して，書かれている内容を端的に表す見出しを付ける
    • one heading, one message

Satisfaction

説明

  • 読み手が「読んでよかった」「わかりやすかった」と感じられること
  • ストレスなく読める体験が提供されていること

アクション

わかりやすい文の書き方

文を書き始めるのはアウトライン設計後
  • 文章はすぐに書き始めるのではなく，まず「構造」＝アウトラインを先に設計する

わかりやすい文を書くにあたって，次の4点を抑える必要があります

  • 係り受けを明確にする
  • 並列関係を明確にする
  • 順序関係を明確にする
  • 「の」は一つの文に２つまでに留める

係り受けを明確にする

説明

  • 誤解を招く文の原因の一つが，係り受けの曖昧さ
  • 係り受けはできる限り近い位置に配置するべき

例

  • ❌ 簡単なチャットアプリの作り方
  • 👍 チャットアプリの簡単な作り方

並列関係を明確にする

説明

  • 並列する要素（AとB、～や～など）は、文法的・意味的に対等な構造で書く必要がある
  • 並列構造が乱れると、何が並列なのか、読み手が混乱する

例

  • ❌ このツールは、設定の保存、読み込み、そしてファイルの圧縮ができます
  • 👍 このツールは、設定の保存・読み込み、ファイルの圧縮ができます

順序関係を明確にする

説明

  • 複数の出来事や手順がある場合は、どの順で発生・実行されるかを明確にすることが重要
  • 順序が不明瞭だと、因果関係や手順が誤解されやすくなる

例

  • ❌ 入力が完了したら、ファイルを保存し、名前を入力してください
  • 👍 入力が完了したら、名前を入力し、その後でファイルを保存してください

「の」は一つの文に２つまでに留める

説明

  • 「の」を多用すると、文の構造が複雑になり、意味があいまいになる
  • そのため、一文に「の」は2つまでに抑えるのが、読みやすさの目安。

例

  • ❌ データ処理の高速化のためのアルゴリズムの最適化手法の調査
  • 👍 データ処理を高速化するための、アルゴリズム最適化手法の調査
  • 👍 アルゴリズム最適化手法について、データ処理を高速化する観点から調査した

アンチパターンと発生原因

Problem 1: なにを書いていいかわからない
Problem 2: あれもこれもと，情報詰め込んでしまう
Problem 3: 自分で説明するとき，何故か説明しづらい
    • headingsとkey takeawaysだけ読んでみたとき，目が止まってしまう or 順番が飛んでしまう
Problem 4: 何が言いたいかわからないheadingsがある
Problem 5: 作成したユーザーマニュアルが読みづらいと言われた
    • ユーザーマニュアルは読者の立場に立った指示やガイドを提供するべき

Appendix: パラグラフと段落の違い

「パラグラフ」と「段落」は、日常的には同じ意味で使われることも多いですが、ドキュメント作成の文脈では以下のような差異が有ります:

用語 視点 意味
段落 見た目 改行による文章の区切り
何を１段落にまとめるかの自由度が高い
パラグラフ 意味 1つの主張を持った論理的な文の集まり
1 paragraph 1 topic

Pragraphの構成

1つのパラグラフは、原則として以下のような構造で成り立っています：

構成要素 説明
topic sentence パラグラフの最初に置かれ、その段落で述べたい中心的な主張やポイントを示す
support sentence 「なぜそう言えるのか？」「どんな意味があるのか？」を展開する

References