良いドキュメントの作成方法を学ぶ（前編）

SHARE

『エンジニアが一生困らないドキュメント作成の基本』を読み、
良いドキュメントを書くためのポイントをいくつか備忘としてまとめます。


そもそも、なぜこの本を手にとったかといいますと、

最近、仕様書を書くのに時間かかる…！
自分こんなに書けなかったのか…。
と、ちょっと凹んだのがきっかけです。

エンジニアとして数年やってきましたが、
ドキュメントを書く方法を初めて学ぼうと思った訳です。

本の概要

この本の章立ては以下のようになっています。

・Chapter1 : 良いドキュメントを効率良く書くために

・Chapter2 : ドキュメントの読み方を理解する

・Chapter3 : 読み手とテーマを選別する

・Chapter4 : テーマを分解する

・Chapter5 : ドキュメントの骨組みを組む

・Chapter6 : 文章を書く

・Chapter7 : わかりやすい文を書く

・Chapter8 : ChatGPTで効率良く書く

・Chapter9 : ドキュメントの構成例

本ブログでは、興味をもった箇所を抜粋しているため、
少しでも詳細を知りたくなったら実際の書籍を購入して読むことをお勧めします。

この前編ではChapter1～Chapter4までを範囲としてまとめ・感想を書いてます。

Chapter1 : 良いドキュメントを効率良く書くために

この本において、ドキュメントは「説明型」、「報告型」、「説得型」の３つに分けて説明されています。

  • 概念や手順を説明する（説明型）…要件定義書、仕様書、マニュアル、作業手順書
  • 知見や活動を報告する（報告型）…報告書、論文・技術ブログ
  • 意見や提案を伝え、相手の行動を促す（説得型）…企画書・提案書

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

「良いドキュメント」＝「ユーザービリティの高いドキュメント」
とのことで、以下の３つの要素をもつものと定義されています。

  • 必要な情報を正しく得られること
  • 効率良く理解できること
  • 不快さがなく、ポジティブに受け止められること

文章を書く前の設計が大事

筆者は「文章を書き始める前に設計の工程が欠かせません」と
ドキュメントを書くために「設計」が大切と述べています。

設計をする上で、以下のことを意識するのがポイントです。

  • 見出しをつける
  • １つの見出しに１つのテーマを持たせる
  • 同じことを複数の箇所に書かない

何を書けばいいかわからない人が、「書ける」ようになるには

ドキュメントを書くことに苦手意識がある方は多いのではないでしょうか。
私も苦手意識がありありです。もうドキュメントアレルギーです。

ブログを書く時もそうなのですが、「まず、そもそも、何を書けばいいのだろう？」と悩みます。この課題の解決のヒントは以下になります。

  • ドキュメントで伝える情報を小さく分解すると、情報を収集しやすくなる
  • 全体のテーマを「なぜ・何を・どうやって」の３つに分解していく
  • ドキュメント種類ごとのテンプレートを使う
  • 生成AIに構成案を考えてもらう


「書けない」と思ったら、「まだテーマの粒度が荒くて分解が足りていないのだ」と考えることです。粒度が荒い…（心にグサッときました）。細かく、サブテーマへと分解して書いていきましょう！

Chapter2 : ドキュメントの読み方を理解する

この本では、ドキュメントを効率良く読む方法も学べました。
余談ですが、受験時の英語学習でもこんな感じで構成を意識して読みましょうと言われたのを思い出しました。

大事なのは、階層構造を意識することです！！！

階層構造の中で５つの要素が持つ役割は以下になり、それらを意識して読むと効率良くドキュメントを読むことができます。

・タイトル（全体のテーマ）…「何が書かれているか」「何が言いたいか」

・見出し（サブテーマ）…テーマの中の「何が書かれているか」「何が言いたいか」

・リード文…タイトルや見出しの補足。読み手を本文へ導く。

・パラグラフ（話題）…「言いたいこと」と「理由や説明」の組み合わせ。

・中心文…パラグラフごとの「言いたいこと」を示す。

Chapter3 : 読み手とテーマを選別する

この章では、数ある読み手やテーマの中から、ターゲットを絞り込むための方法が解説されていました。

大事なことは、ドキュメントの目的を明確にすること。
「誰に伝えるか（読み手）」と「何を伝えるか（テーマ）」を考えましょう。

誰に伝えるか（読み手）を選別する

ポイントとしては以下の３つがあります。

  • 読み手の知識レベル
  • 読み手の目的
  • 読み手の立場や役割

ドキュメントを書く際に「色んな人が読むだろう」と思って、ぼんやり書き始めることが多かったのですが、読み手の立場や役割を理解して書かないと、ドキュメントが複雑化してしまう。これは共感の嵐でした。

では、どうやって理解すればいいのかというと、関係者にヒアリングすることが大切とのこと。読み手に聞いてしまうのが一番早い解決策ですね。（コミュ力…大事！）

何を伝えるか（テーマ）を選別する

テーマを選別する中で、読み手の目的を意識することが大事です。
なぜならテーマは、読み手の目的に紐づくからです。

例えば、「エンジニアに、ドキュメントの書き方を伝える」といった目的だと少し抽象的です。

「どんなエンジニアのために」、「どんな方法を伝えるか」といったように具体的な目的を設定しましょう。例えば、「文章をうまく書けないエンジニアのために情報を構造化して文章に落とし込む方法」といった感じです。

このように、読み手の目的を具体化してテーマを絞ることで、何を伝えるか明確化されます。

Chapter4 : テーマを分解する

この章のポイントは、「全体から部分へ」「概要から詳細へ」という整理をしていくことです。
以下のテーマを構成する基本要素３つをおさえると適切な分解ができます。

  • なぜ（Why）
  • 何を（What）
  • どうやって（How）

例えば外部設計書の読み手の目的は「機能の仕様を知ること」なので、こんな分解になります。
外部仕様書を書くことがあったので、本書の外部仕様書の例は参考になりました。

ただ、具体的な文章の書き方は記載されていないため、テクニカルドキュメントや設計書の書き方関連の本をもう少し漁ったほうがよさそうでした。

個人的な感想

いざドキュメントを書こうと思っても、
ユーザーが求めているドキュメントとギャップを感じる。

そこで、この本を読みました。
この本の対象者はエンジニアですが、他の業種の方にも役立つような
あらゆる文章を書く上で基本的なポイントが書かれていました。

なので、「こんなのあたりまえじゃん」と感じる方もいるかと思います。

私のように日々の業務でなかなかドキュメントを書く際に
全体像・目的を意識できていないという方は、
辞書代わりに1冊おいておくのもいいかもしれません。

前の記事

【洋楽和訳】Espresso | Sabrina Carpen…