SHOEISHA iD

※旧SEメンバーシップ会員の方は、同じ登録情報(メールアドレス&パスワード)でログインいただけます

CodeZine編集部では、現場で活躍するデベロッパーをスターにするためのカンファレンス「Developers Summit」や、エンジニアの生きざまをブーストするためのイベント「Developers Boost」など、さまざまなカンファレンスを企画・運営しています。

翔泳社の本(AD)

簡潔でわかりやすいドキュメントを書くときに最低限押さえておくべき4つのポイント

  • X ポスト
  • このエントリーをはてなブックマークに追加

 どんなエンジニアも、コードだけ書いていれば仕事になるわけではありません。プロダクトや技術についてエンジニア同士で、あるいは専門外の人にわかりやすく伝えなければならない機会は多く、ドキュメントが必要な場合も多々あります。そうしたドキュメントを誰が読んでも理解できるものにするには、どんなことに気をつけて書けばいいのでしょうか。『技術者のためのテクニカルライティング入門講座 第2版』(翔泳社)から、4つのポイントを解説します。

  • X ポスト
  • このエントリーをはてなブックマークに追加

 本記事は『技術者のためのテクニカルライティング入門講座 第2版』(著:髙橋慈子)の「第2章 わかりやすく、簡潔な文章を書くテクニック」から一部を抜粋したものです。掲載にあたって編集しています。

一文一義で書く

1つの「主題=伝えたいこと」に絞って書く

 理解しやすい文章を書く基本のセオリーとして、テクニカルライティングでは「一文一義で書く」ことを基本として学びます。これは、1つの文には、1つの主題に絞って書く、という意味です。主題をもった「文」がまとまって「文章」を構成します。

 なぜ、1つに絞るのか。その理由は、人の文章の読み方、理解の仕方に合わせた文章にするためです。人が文章を読むときには、句点「。」を区切りとして読み進めていきます。区切りがきたときに、「この文では、このような内容が書いてあった」と整理できると、スムーズに文章を読み進めることができ、全体の内容が理解しやすくなります。

 一方、複数の内容が盛り込まれている文は、区切りがどこになるのかを考え、それぞれの内容を整理しながら読み進めなければなりません。その分、読み手に負荷がかかり、理解しにくくなると言われています。

複数の内容が盛り込まれた文章は理解しにくい

 では実際に、複数の内容が盛り込まれている次の文を読んでみてください。あるクラウドサービスの説明文を想定しています。

BEFORE 複数の内容が一文に盛り込まれている例

「HRTN CLOUD」はクラウド型ビジネスコミュニケーションツールで、ファイル管理、プロジェクト管理、メッセンジャー、グループチャット機能をもっているため、資料やプロジェクトの情報を共有し、コミュニケーションの迅速化を図ることができます。/区切り

AFTER 一文一義に書き直した例

「HRTN CLOUD」はクラウド型ビジネスコミュニケーションツールです。/区切り
ファイル管理、プロジェクト管理、メッセンジャー、グループチャットなどの機能があります。/区切り
資料やプロジェクトの情報を共有し、コミュニケーションの迅速化を図ることができます。/区切り

 BEFOREでは複数の内容が盛り込まれ、一文が長くなっています。文末まで読んでいくのに少し時間がかかることでしょう。何が書かれているのかを整理するため、何度か読み返したかもしれません。

 次に、一文一義に区切ったAFTERの改善例を読みます。文が短く区切られているため、読み進めやすいことに気づくでしょう。

伝えたいキーワードを書き出しておく

 文を書くときに、「伝えたいことが多く、長くなってしまう」という人は、一文一義の文をいきなり書くのではなく、あらかじめ伝えたいキーワードを書き出しておきましょう

 各ポイントで最も伝えたいことは何かを明確にし、ポイントで述べる内容のキーワードを抜き出しておくと、伝えるべき情報が絞り込まれていきます。

 キーワードを並べ、一緒に説明すべき情報はグルーピングしておきます。順番についても検討したら、抜き出したキーワードを盛り込みながら文を書いていきます。

文を長くしない。「〜(だ)が」、「〜ので」で文をつながない

中堅以上の技術者に多い、書き癖パターン

 ライティング研修や文章力講座に参加される、文章を改善したいと思っている方の中には、ある書き癖をおもちの方が一定数いらっしゃいます。「文章を書くことは苦手ではないが、言いたいことが多いため、結果的に文章が長くなってしまう」というものです。

 このパターンは中堅以上の方に多く、皆さん、知識も経験も豊富です。その知識や業務で得た情報を存分に伝えたいと思うあまりに、文章が長くなってしまうのでしょう。このタイプの方からは、書き上げた文章を読んだ上司から、「もっと簡潔にまとめるように」と注意されることがあると聞きます。

 長い文によく使われる表現パターンが、「〜(だ)が」や「〜ので」で文章をつないでいるものです。次の最初の例を読んでみてください。「〜広く普及しているが」や「利用が少ないので」と、説明を加えることで文が長くなっていることがわかるでしょう。複数の内容が一文に盛り込まれ一文一義になっていないことも、文が長くなる原因です。

文を区切り、重要な内容を前に移動する

 「〜(だ)が」や「〜ので」を使った長い文章を改善すべき理由は、文が長くて読みにくいからだけではありません。文の中で最も伝えたいことが、文の最後にきているからなのです。

 同じ文を短く区切って改善した例と、さらに順番を変えて、重要な部分を先に書いて改善した例とを比べてみてください。伝えたいことが最初に述べられ、何を言いたいのかが明確に伝わる文章になりました。

書き終わった後に見直して修正しよう

 文が長くなる原因の「〜(だ)が」や「〜ので」を使わないようにする効果的な方法は、「書き終わった後に何度も見直して練り上げること」、つまり「推敲」をすることです。日常のやり取りで書いているメールを見直してみてください。

 書き癖としてつい使ってしまっているなら、書かないように気を付けるのではなく、書き終わった後で推敲しましょう。書いている最中に注意しながら進めていくのは、難しいものです。伝えるべき内容が疎かになっては本末転倒です。

 そこで、まずは書き上げて、それから文を区切ったり、順番を変えたりすることを検討するほうが、文章がよくなります。結果的に文書作成の時間短縮にもつながります。

BEFORE 「〜(だ)が」、「〜ので」で文が長くなっている例

現在、個人ユーザーを中心にスマートフォン用のチャットサービスが広く普及しているが、ビジネスでの利用については未だ利用者が少ないので、新たなサービス展開を検討するため、以下に提案資料をまとめた。

AFTER 文を区切って、改善した例

現在、個人ユーザーを中心にスマートフォン用のチャットサービスが広く普及している。一方、ビジネスでの利用については未だ利用者が少ない状況である。新たなサービス展開を検討するため、以下に提案資料をまとめた。

文の順番を変えて、重要な内容を先に書き、改善した例

新たなサービス展開を検討するため、以下に提案資料をまとめた。

■現状分析
現在、個人ユーザーを中心にスマートフォン用のチャットサービスが広く普及している。一方、ビジネスでの利用については未だ利用者が少ない。

一文を短く。50字以内で収めるように

理解しやすい文の長さは50字以内

 一文に複数の内容が入っていると読みにくく、理解しにくいものです。つまり一文は短く書いたほうが、読みやすく、理解しやすくなります。「短く書く」文の目安は、一文で50字以内です。この分量は、文の区切りまで一気に読め、内容を理解しやすく、認知しやすい情報量だからだと言われています。

 次の例を読んでみてください。一文を106字で書いている長い文と、49字にした改善後の短い文です。短い文はスッキリと読みやすく、一気に読み進められます。

 実際、新聞や技術系のWebサイトの文をチェックしてみると、その多くがおおよそ50〜60字程度の文で書かれています。文体は「である体」で書かれることが多く、一文一義でまとめられています。加えて一文一文が短く区切られており、スムーズに読み進められることに気づくのではないでしょうか。

 簡潔で読みやすい文章表現の例として、新聞や、技術系のWebサイトの文を参考にするとよいでしょう。

BEFORE 1文が長い例(106字)

チャットやメッセンジャー機能は、個人のユーザーを中心にネット時代の新しいコミュニケーションツールとして普及していますが、データ管理面やセキュリティーの面で企業での利用には不安な点もあると考えられているのが実情です。

AFTER 1文を短くした例(49字)

チャットやメッセンジャー機能のビジネス利用は、データ管理やセキュリティーの面から不安視されています。

A4判の文書なら、1行+10字

 一文が50字以上の長い文になっていないかを簡単に確認する方法を知っておきましょう。ビジネスの文書作成でよく使われているWordでは、A4サイズの横書きの文書の初期設定で、1行40字に設定されています。50字とは、1行プラス10字です。2行を超えたら80字以上になっています。区切ることができないか、不要な部分がないかをチェックするとよいでしょう

 メール文の場合はWordに比べて文字数が数えにくいですが、パソコン画面で3行以上になっていないかを目安にすると、短い文章になるでしょう。

5W2Hを盛り込み、曖昧な文章にしない

「知っているはず」は自分視点。省略不可の情報とは

 簡潔に書くことは、情報量を減らすという意味ではありません。「これは知っているはずだから」や「これでわかるだろう」と自分視点で書くのは危険です。省いてはいけない情報が何かを意識し、しっかりと盛り込みます

 次の社内の関係者に宛てたメール文を例に説明しましょう。本文を一文にまとめた短い内容です。BEFOREのメール文は、何を言いたいかは伝わってきますが、期待する次の行動につながる情報が抜けています。読み手によって解釈が異なる可能性があります。

BEFORE 具体的な情報が抜けている社内メール文

件名:レビューについて

ソフトウェア管理ツール概要書について、お忙しい中すみませんが、関係者の皆さんは各自、来週いっぱいまでにレビューをお願いします。

シス2課 高橋より

AFTER 「何を、いつまでに、どうしてほしいか」を具体的に書いた社内メール文

件名:【依頼】ソフトウェア管理ツール概要書レビュー

関係者各位


ソフトウェア管理ツール概要書のレビューをお願いします。技術的な内容の確認、使い勝手などを検討いただき、よりよいツールにしていくために、レビューのコメントを書き入れてください。
レビューするファイルは、以下からダウンロードしてください。
   ¥xxxx¥xxxxx¥xxxxx.xlsx
コメントを書き込んだレビューファイルは、来週、X月X日 17:00までに、私までメールにて送付してください。
お忙しい中、恐縮ですがご協力をお願いします。

(署名)

 たとえば、「来週いっぱい」と言われたら、来週金曜日の定時、17時や17時半だと考える人もいれば、遅い時間になっても金曜日中に提出すればいいだろうと考える人もいるでしょう。再来週月曜日の朝までに送っておけばいいと思う人もいるかもしれません。このように読み手の解釈にばらつきがあると、次の作業の予定が立てにくくなります。

 また、どのように提出してほしいのかが具体的に書かれていないので、初めてレビューに参加するメンバーがいる場合、その人なりに考えた方法で提出してくるかもしれません。その場合は、他のレビューファイルと同じ形式でまとめる手間が発生するかもしれません。

自分視点で、必要な情報を省いてはいけない
自分視点で、必要な情報を省いてはいけない

5W2Hを書き出しておく

 文書の読み手に期待する行動を取ってもらい、仕事を確実に進め、かつスピードアップするには、「5W2H」を内容に応じて盛り込むことが大切です。

 国語の授業では、5W2Hではなく5W1Hの「いつ、どこで、誰が、何を、なぜ、どのように」だと言われます。これに加え、ビジネスでは必要に応じて「いくらで(How much)」を盛り込むため、5W2Hと言われるのです。

 先ほどのメール文のBEFOREの例では、「いつまでに、誰に、なぜ、どのように」という具体的な情報が書かれていません。AFTERの改善例のように具体的に書くことで、何をしてほしくて送ってきたメールなのかが読み手に明確に伝わるようになります。具体的に時間や日付を書いておくことで、後から読み返すときにも間違いがなくなることでしょう。

 行動につながる具体的な情報を漏らさないようにするには、あらかじめメモなどに、これらの情報を書き出しておきます。返信してもらう期日、打ち合わせの日時、場所などを書き出し、相手にわかりやすく伝わるかどうかを確認しておけば、メールや文書での情報不足や記入ミスがなくなります。

5W2Hを書き出しておく
5W2Hを書き出しておく
次の行動につながる内容を具体的に書く
次の行動につながる内容を具体的に書く
技術者のためのテクニカルライティング入門講座 第2版

Amazon  SEshop  その他

 
技術者のためのテクニカルライティング入門講座 第2版

著者:髙橋慈子
発売日:2024年12月18日(水)
定価:2,640円(本体2,400円+税10%)

本書について

本書では、忙しい技術者の方でも「テクニカルライティング」を通じて、相手に伝わる技術文書を効率よく書けるようになるテクニックを多数紹介していきます。ユーザーマニュアルや障害報告書、提案書といった実務直結の例を多数紹介しているため、すぐに業務に役立てられます。

この記事は参考になりましたか?

  • X ポスト
  • このエントリーをはてなブックマークに追加

【AD】本記事の内容は記事掲載開始時点のものです 企画・制作 株式会社翔泳社

この記事は参考になりましたか?

この記事をシェア

  • X ポスト
  • このエントリーをはてなブックマークに追加
CodeZine(コードジン)
https://codezine.jp/article/detail/20607 2024/12/25 07:00

イベント

CodeZine編集部では、現場で活躍するデベロッパーをスターにするためのカンファレンス「Developers Summit」や、エンジニアの生きざまをブーストするためのイベント「Developers Boost」など、さまざまなカンファレンスを企画・運営しています。

新規会員登録無料のご案内

  • ・全ての過去記事が閲覧できます
  • ・会員限定メルマガを受信できます

メールバックナンバー

アクセスランキング

アクセスランキング