伝わるドキュメントを書けるエンジニアになりたい

はじめに

ご覧いただきありがとうございます。

本記事は、「エンジニアとして、伝わりやすくわかりやすいドキュメントを作成できるようになりたい」と思った私が、「エンジニアが一生困らないドキュメント作成の基本」という本を読んで得られた学びを書いたものです。

私は普段webエンジニアとして働いています。エンジニアはよくドキュメントを作成します。例えば、新機能を開発する際は、要件や仕様をドキュメントにまとめてメンバーやマネージャーに伝えます。それをもとに議論したりレビューを受けたりもします。また、新しい機能がリリースされれば製品マニュアルを書きます。

このように、エンジニアはドキュメントを書く機会が思いの外多いです。わかりやすいドキュメントを作成する力が向上すれば仕事のパフォーマンスを上げられると思い、本書を読んでみることにしました。

以下、私が本書を読んで大切だと思ったこと、すぐに業務に活かせそうだと思ったことをピックアップしてみました。

伝わるドキュメントを作成するために意識したい10のこと

1. 文章を書く前に設計を考える

ドキュメントを作成する際は、いきなり文章を書き始めるべきではなく、先にドキュメントの設計をすべきです。具体的には、伝えたいテーマをいくつかの項目に分解し、アウトラインを考えることが重要です。

最初にドキュメントの設計をすることで以下のようなメリットがあります。

• 情報の散在、重複を防げる
• 何を書くべきかが明確になり文章を書きやすくなる

2. ドキュメントは階層構造であることを念頭に置く

ドキュメントは階層構造を持っています。以下のようなイメージです。

• タイトル(= ドキュメントのテーマ)
  • 見出し1 (=サブテーマ)
    • パラグラフ1
      • 中心文(言いたいこと)
      • 理由、説明、具体例
    • パラグラフ2
      • 中心文(言いたいこと)
      • 理由、説明、具体例
  • 見出し2 (=サブテーマ)
    • パラグラフ1
      • 中心文(言いたいこと)
      • 理由、説明、具体例
    • パラグラフ2
      • 中心文(言いたいこと)
      • 理由、説明、具体例

階層構造を意識してドキュメントの構成を考えることで、読み手に取って以下のようなメリットがあります。

• ドキュメントの全体像を理解しやすい
• 必要な情報にアクセスしやすい

3. 読み手とテーマを明確にする

「だれに何を伝えるのか」が明確になると、シンプルで伝わりやすいドキュメントになります。

例えば、機能の仕様を伝えるドキュメントを作成する場合、それが同じチームの開発者に向けたものなのか、クライアントに向けたものなのかで内容が大きく変わりそうです。

そのためにあらかじめ誰に何を伝えたいのかを具体的に言語化しておくべきです。

悪い例

• 機能の使い方を伝える

よい例

• これから機能を使い始めるIT初心者のユーザーに、機能の概要と導入手順を伝える

こうすることで、適切な情報を適切な粒度と表現で伝えることができるようになります。

4. テーマを分解する

伝えたいテーマを適切に分解することで、階層構造が明確になります。

• テーマ
  • サブテーマ1
    • 話題1
    • 話題2
  • サブテーマ2
    • 話題1
    • 話題2
  • サブテーマ3
    • 話題1
    • 話題2

テーマを適切に分解すると、複雑な情報が整理されるので、読者にとって理解しやすい文章を書けるようになります。また、テーマを分解することは、情報の探しやすさにもつながります。読者は見出しを見ながらドリルダウンで必要な情報を探しに行くので、情報が適切に分解されていることが重要です。さらに、執筆者にもメリットがあります。書くべき内容が具体化されるので効率的に文章を書けます。

5. 「なぜ」「何を」「どうやって」に分解する

テーマを適切に分解するとわかりやすいドキュメントになりますが、適切に分解するためには**「なぜ」「何を」「どうやって」**の構造を意識することが重要です。

• なぜ(why)
  なぜこの情報が必要なのかを読者に伝えるための要素です。プロダクトの機能説明であれば、読者にとってなぜそのプロダクトや機能が必要なのかを伝えます。企画書であれば、なぜその企画が必要なのかを伝えます。

• 何を(what)
  それは何なのかを伝えるための要素です。この機能はどんなプロダクトなのか、機能なのかを伝えます。企画であれば、どのような企画なのかを伝えます。

• どうやって(How)
  どうやってそれを実現するのかを伝えます。プロダクトや機能であれば使い方や設定方法、企画であればその企画を実現する方法です。

テーマを分解する際、まずは「なぜ」「何を」「どうやって」に分解し、さらにその中を情報のまとまりごとに分解していきます。

情報を分解するときは、以下の点に注意します。

• 全体から部分へ
• 抽象から具体へ
• 読み手の目的ごとに

「読み手の目的ごとに」とは、例えば、ユーザーに向けた製品マニュアルであれば、ユーザーは特定の機能の使い方を知りたくてマニュアルを見ることが多いでしょうから、情報は機能単位で分解されているべきだ、ということです。

6. 読み手が構成を掴めるようにアウトラインを考える

ドキュメントにおけるアウトラインとは、章、節、項などの見出しを階層にまとめたものです。執筆者にとってはドキュメントの設計図であり、読者にとっては必要な情報にアクセスするための地図の役割となります。

アウトラインを書くには、テーマを適切に分解できていることが重要です。

また、各項目の順序も重要です。順序を考えるときは、以下のポイントに注意します。

• 既知から未知
• 重要なものから
• 時系列準
• ニーズの大きいものから

各項目と順序が決まったら、適切な見出しを付けます。

見出しは、本文で言いたいことを端的に表した内容にします。小説ではないので、本文を読まないと答えがわからないといった具合に情報を隠す必要はありません。

7. 1つのパラグラフに1つの主張が含まれるように書く

アウトラインができたら、見出しごとに文章を書いていきます。

一つのパラグラフで言いたいことは1つに絞り、冒頭でズバッと簡潔に書きます。これを中心文といいます。そのあとに中心文を説明する内容を書きます。これを支持文といいます。支持文には、理由、説明、具体例などを書きます。

8. 1文1義を意識する

一つの文章で伝えたいことはひとつにします。先ほど、1パラグラフにつき言いたいことは一つと書きましたが、それは言いたいことを伝えるための各文章も同じです。これを意識しないと、句読点が多かったり、長くて読みづらい文章になってしまいます。

一つの文章に入れる情報をなるべく少なくしよう、と意識しておくことが大切です。

9. 読み手の視点を意識して受動態と能動態を使い分ける

読み手の視点に立ち、読み手が価値を感じるような表現にすることが重要です。例えば、本書では以下のような例が提示されています。

悪い例

アプリの自動アップデートが有効になっていると、定期的にアップデートの有無をチェックし、自動的にアプリをアップデートします。

よい例

アプリの自動アップデートを有効にすると、常に最新版のアプリを使用できます。

このように、受動態と能動態を意識することで、読み手がメリットを感じやすい文章になります。

10. わかりやすい文章にするためのテクニックを知っておく

わかりやすい文章を書くためのテクニックがたくさん提示されていたので、私が重要だと思ったものをいくつかピックアップします。

具体的に書く
○○は簡単です、というような文章は何が簡単なのか伝わらないので、補足説明を付け加えるべきです。具体的にするため、数値情報を入れるようにすることも効果的です。

読み手にアクションを促すときは行動を具体的に書く

○○を確認してください、だけだとアクションが抽象的です。○○画面のxxタブで、○○の設定がONになっていることを確認してください、といった具合です。

係り受けに注意する

日本語は、語順や句読点に気を付けないと誤った意味で解釈される可能性があります。本書では以下のような例が出されています。

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

これは、「簡単」が「チャットアプリ」にかかっているのか「作り方」にかかっているのかわかりづらいです。

以下のように直すと意味が一意に定まります。

• 簡単な、チャットアプリの作り方 (句読点の使用)
• チャットアプリの簡単な作り方 (語順の入れ替え)

並列の項目は同じ表現で書く

並列な項目を列挙することがあると思います。その際は、表現を統一することで並列であることが伝わりやすくなります。小説ではないので、多様な表現をする必要はありません。

ポジティブに伝えるために肯定文で書く

○○できません、よりも○○できます、という書き方のほうが読み手が気持ちよく読むことができます。例外として、注意を促す場合には否定形で書く方が効果的な場合もあります。xxしないでください、という具合です。必要に応じて使い分けます。

過剰に丁寧な言葉を使わない。

○○してくださいますようお願いいたします、のような表現は冗長です。省略して問題なければ省略すべきです。

おわりに

以上が、本書を読んでわたしが学んだことになります。本書にはたくさんの具体例が掲載されているので、本記事を読んで興味を持った方はぜひこちらの本を読んでみることをおすすめします。

最後までお読みいただきありがとうございました。

参考文献

• エンジニアが一生困らない ドキュメント作成の基本