テクニカルライティングの基本

by Naohiro Nakata

Slide 1

Slide 1 text

テクニカルライティングの基本 2022年5月17日開運研修2022 開発本部テクニカルコミュニケーションチーム仲田 1

Slide 2

Slide 2 text

2 仲田尚央 Nakata Naohiro @naoh_nak 開発本部テクニカルコミュニケーションチームテクニカルライター/ローカライズ職能マネージャーお仕事の内容： ⚫ サイボウズ製品のUIテキストを書く ⚫ 製品のマニュアルやヘルプを書く ⚫ それらを他の言語に展開する（ローカライズ）

Slide 3

Slide 3 text

テクニカルライティングは 3 読者や目的に合わせて技術をわかりやすく伝える手法です。

Slide 4

Slide 4 text

みなさんは、これから「ドキュメント」を書く機会が多くあります。 4

Slide 5

Slide 5 text

⚫ 報告書や企画書を書く ⚫ 業務マニュアルを書く ⚫ 製品や機能の解説を書く ⚫ 作業手順書を書く ⚫ 製品の仕様書を書く ⚫ … 5

Slide 6

Slide 6 text

ドキュメントは多くの人に読まれます 6 業務マニュアル

Slide 7

Slide 7 text

書き手の工夫で、多くの人の時間を節約できます 7 業務マニュアル

Slide 8

Slide 8 text

書き方の方法論を学ぶことで、書き手の時間も節約できます 8 業務マニュアル

Slide 9

Slide 9 text

チームワークのために、情報共有は欠かせません。良いドキュメントを書くことは、効率的な情報共有に繋がります。 9

Slide 10

Slide 10 text

テクニカルライティングの適用対象 ⚫ いわゆる「実用文」が求められるもの ⚫ 議事録 ⚫ 報告書 ⚫ 技術書・解説書 ⚫ 仕様書 ⚫ マニュアル・FAQ などなど 10

Slide 11

Slide 11 text

ドキュメントの前提1 - 求める情報が人によって違う 11 業務マニュアル作業Aの手順を知りたい。入社したばかりで何もわからん。今度担当することになった業務Bについて、一通り全部学びたい。インストールが必要なツールを知りたい。・・・

Slide 12

Slide 12 text

ドキュメントの前提2 - 情報の探し方も違う 12 業務マニュアル作業Aの手順を知りたい。入社したばかりで何もわからん。今度担当することになった業務Bについて、一通り全部知っておきたい。インストールが必要なツールを知りたい。・・・知りたいことが明確知りたいことが曖昧網羅的に知りたい

Slide 13

Slide 13 text

ドキュメントの前提3 – 一意に伝わる必要がある 13 ✕ ✕ ✕

Slide 14

Slide 14 text

ドキュメントの前提4 – 一部しか読まれない 14

Slide 15

Slide 15 text

テクニカルライティングの要素 15 Effectiveness 必要な情報を正しく得られる Satisfaction 不快さがなく、肯定的に受け止められる Efficiency 効率よく理解できるユーザビリティーの定義（ISO 9241-11）から

Slide 16

Slide 16 text

それぞれの要素に対して取る手段 16 Effectiveness 必要な情報を正しく得られる Satisfaction 不快さがなく、肯定的に受け止められる Efficiency 効率よく理解できる • 曖昧さを排し、明確に書く • できるだけ具体的に書く • 誤解なく読める文章で書く • 情報を適切に整理、構造化する • どこに何が書いてあるかをわかりやすくする • 簡潔で読みやすい文章で書く • 必要な情報だけを書く • 肯定的な表現で書く • ですます調で書く（過剰な敬語にはしない）

Slide 17

Slide 17 text

テクニカルライティングの進め方 1. 伝える情報を整理する 2. アウトラインを作る 3. わかりやすく、簡潔な文章で書く 17

Slide 18

Slide 18 text

伝える情報を整理する 18

Slide 19

Slide 19 text

整理の鉄則 19 概要から具体へまたは全体から部分へ

Slide 20

Slide 20 text

20 伝えるテーマテーマ1 テーマ1-1 テーマ1-1-1 テーマ1-1-2 テーマ1-2 テーマ2 テーマ2-1 テーマ2-2 概要全体具体部分具体例で分解構成要素で分解

Slide 21

Slide 21 text

書籍や文書の場合 21 伝えるテーマテーマ1 テーマ1-1 テーマ1-1-1 テーマ1-1-2 テーマ1-2 テーマ2 テーマ2-1 テーマ2-2 章節項

Slide 22

Slide 22 text

Webの場合 22 伝えるテーマテーマ1 テーマ1-1 テーマ1-1-1 テーマ1-1-2 テーマ1-2 テーマ2 テーマ2-1 テーマ2-2 カテゴリーページ見出し

Slide 23

Slide 23 text

全体から部分へと分解する 23 kintone アプリレコードフィールドコメントビュー（一覧）アクセス権・・・スペース公開スペース非公開スペースゲストスペースピープルメッセージ

Slide 24

Slide 24 text

概要から具体へと分解する 24 スマートフォン Android Pixel Xperia Galaxy ・・・ iOS iPhone Pro Max iPhone Pro iPhone mini ・・・

Slide 25

Slide 25 text

順に説明を展開していく 25 スマートフォン Android Pixel Xperia Galaxy ・・・ iOS iPhone Pro Max iPhone Pro iPhone mini ・・・段階を追って知識を付け加えていくことが、わかりやすさに繋がる

Slide 26

Slide 26 text

情報を適切に分解すると、読者が情報を探しやすくなる 26 スマートフォン Android Pixel Xperia Galaxy ・・・ iOS iPhone Pro Max iPhone Pro iPhone mini ・・・前知識がない人は、最初から読み、興味を持った項目へと進む特定の知識が欲しい人は、その項だけを読むさわりだけを知りたい人は、概要だけを読むどこに何が書いてあるかがわかるよう、適切なタイトルと見出しを付けよう

Slide 27

Slide 27 text

分解には複数のやり方がある 27 スマートフォンコミュニケーション・・・・・・ニュース・・・・・・買い物ナビゲーム・・・

Slide 28

Slide 28 text

情報整理の例 - 良いヘルプの要素を分解する ⚫ まず、良いヘルプの要素を具体化する ⚫ 要素ごとに、どうすれば満たせるかを考察していく 28 良いヘルプ役に立つターゲットユーザーの設定情報の収集方法探しやすい情報の分類タイトルや見出しの付け方検索最適化わかりやすい用語の統一読みやすい文章の書き方図解正しい・・・

Slide 29

Slide 29 text

情報整理の例 - 説明の構成に反映する 29 誰に何を伝えるかを整理する『ヘルプサイトの作り方』章構成良いヘルプ役に立つターゲットユーザーの設定情報の収集方法探しやすい情報の分類タイトルや見出しの付け方検索最適化わかりやすい用語の統一読みやすい文章の書き方図解正しい・・・ユーザーの使い方を意識して構成を設計するユーザーの動線からナビゲーションを設計するスタイルガイドと用語集を準備する記事を書く - 文章と図解のテクニック・・・

Slide 30

Slide 30 text

アウトラインを作る 30

Slide 31

Slide 31 text

記事で伝える情報を書き出すテーマ： kintoneでアプリを開発する方法を解説する伝えることを書き出した例： ⚫ アプリ開発を開始する前に必要な準備 ⚫ 開発中のアプリを保存し、中断する方法 ⚫ 保存したアプリを開いて、アプリ開発を再開する方法 ⚫ 簡単なアプリを例にしたアプリ開発手順 ⚫ アプリのアイコンの作り方 ⚫ 開発したアプリに機能を追加する方法 ⚫ エラーへの対処方法 31 ✓ この段階では、順番や言葉の表現などの細かいことは気にしない ✓ 情報を漏れなく洗い出すことを重視ポイント

Slide 32

Slide 32 text

書き出した情報を整理する伝える情報を整理した例： ⚫ アプリ開発の全体の流れ ⚫ 簡単なアプリを例にしたアプリ開発手順 ⚫ アプリ開発を開始する前の準備 ⚫ 開発手順 ⚫ アプリのアイコンの作り方 ⚫ 開発中のアプリを保存し、中断する方法 ⚫ 保存したアプリを開き、アプリ開発を再開する方法 ⚫ エラーへの対処方法 ⚫ 開発したアプリに機能を追加する方法 32 ✓ まず概要を述べる ✓ 読者がどのように情報を探そうとするかを意識して、情報を整理する ✓ どのタイミングで必要になる情報かを意識して、項目を並び替えるポイント

Slide 33

Slide 33 text

見出しを決める見出し構造の例： ⚫ アプリ開発の流れ ⚫ アプリを開発しよう ⚫ 開発を始める前に ⚫ ○○○を設定しよう ⚫ ○○○を設定しよう ⚫ ○○○を設定しよう ⚫ アプリのアイコンを作ろう ⚫ アプリ開発を中断する場合 ⚫ アプリ開発を再開するには ⚫ アプリ開発中にエラーになったら ⚫ アプリに機能を追加しよう 33 ✓ 読者が次の情報を読み取れる言葉にすることを意識する： ⚫ 見出しに続く本文に何が書かれているか ⚫ どのようなときに読む必要があるのかポイント

Slide 34

Slide 34 text

わかりやすく、簡潔な文章で書く 34

Slide 35

Slide 35 text

書くときの心構え ⚫ 読者の行動をイメージしながら書くどんな人が、どんな情報を、どのように探すか ⚫ （自分ではなく）読者の視点で書く ⚫ 簡潔に、できるだけ短文で書く ⚫ 重要なことから書く 35

Slide 36

Slide 36 text

重要なことから書く 36 ⚫ Before システムを正常に起動できなくなる恐れがあるので、アップデート中は電源を切らないでください。 ⚫ After アップデート中は電源を切らないでください。システムを正常に起動できなくなります。 ✓ ドキュメントは、一部しか読まれないことを前提に書く ✓ 情報に優先度を付けて、優先度が高いことを先に書くポイント

Slide 37

Slide 37 text

一文一義で書く ⚫ Before サイボウズ Officeは、クラウド型グループウェアで、情報を共有する各種機能、メッセージ機能やワークフロー機能などを備え、使いやすさが特長です。 ⚫ After サイボウズ Officeは、クラウド型グループウェアです。情報を共有する各種機能、メッセージ機能やワークフロー機能などを備えています。使いやすさがサイボウズ Officeの特長です。 37 ✓ 1つの文には、1つの事柄だけを書く ✓ 1文に複数の事柄が詰め込まれていると、内容を整理しながら読まなくてはならなくなるポイント

Slide 38

Slide 38 text

簡潔に書く 38 ⚫ Before ほかのユーザーの連絡先を確認でき、また、ほかのユーザーにメッセージを送ることもできます。 ⚫ After ほかのユーザーの連絡先を確認できます。また、ほかのユーザーにメッセージを送ることもできます。 ⚫ さらに改善ほかのユーザーの連絡先を確認できます。また、ほかのユーザーにメッセージを送ることもできます。 ✓ 簡潔、短くを常に意識する ✓ 「したがって」「または」などの接続詞も、不要なことが多いポイント

Slide 39

Slide 39 text

読者の視点で書く 39 ⚫ Before ニュースレターに登録いただくと、製品のアップデート情報をメールでお送りします。 ⚫ After ニュースレターに登録すると、製品のアップデート情報をメールで受け取れます。 ✓ 読者の視点で書くことが、読みやすさと、わかりやすさに繋がる ✓ システムが主語になっていると、自分視点に置き換えながら読まなくてはならなくなるポイント

Slide 40

Slide 40 text

能動態と受動態を使い分ける 40 ⚫ Before [削除]をクリックすると、すべてのデータを削除します。 ⚫ After [削除]をクリックすると、すべてのデータが削除されます。 ✓ 読者の視点で書くと、読者の操作は能動態、システムの動作は受動態になるポイント能動態受動態

Slide 41

Slide 41 text

できるだけ具体的に書く 41 ⚫ Before メール通知の設定を確認してください。間隔を少しだけ空ける必要があります。 ⚫ After メール通知が有効になっていることを確認してください。 3～5mmの間隔が必要です。 ✓ 曖昧な表現は、書き手の意図通りに伝わらない ✓ 具体的に書く努力をポイント

Slide 42

Slide 42 text

肯定形で書く 42 ⚫ Before 5名以上の予約は受け付けられません。 ⚫ After 4名まで予約できます。 ✓ 否定表現は、理解に時間がかかるだけでなく、ネガティブな印象を招く ✓ 肯定形に書き換えることで、簡潔でポジティブな印象になるポイント

Slide 43

Slide 43 text

二重否定を使わない 43 ⚫ Before ファイルA以外は削除しないでください。 ⚫ After ファイルAだけを削除してください。 ✓ 否定表現は、1つの文に1つまで ✓ 二重否定は文章をわかりづらくし、読者の混乱を招くポイント

Slide 44

Slide 44 text

係り受けを明確にする 44 ⚫ Before 消毒液Aのように刺激の強くない消毒液を使ってください。 ⚫ After 消毒液Aのような、刺激の強くない消毒液を使ってください。または消毒液Aのように刺激の弱い消毒液を使ってください。 ✓ 係り受けが不明確な文章は、まったく逆の意味に受け取られることがあるポイント消毒液Aは使って良いの？

Slide 45

Slide 45 text

主語や目的語と、述語を近づける 45 ⚫ Before データは、自動同期を無効にした場合は手動で同期しない限りバックアップされません。 ⚫ After 自動同期を無効にした場合は、手動で同期しない限りデータはバックアップされません。 ✓ 文が長くなるときは、主語や目的語と述語を近づけると読みやすくなるポイント

Slide 46

Slide 46 text

列記には箇条書きを使う 46 ⚫ Before 名前、住所、メールアドレス、電話番号、および誕生日の入力は任意です。 ⚫ After 次の項目の入力は任意です。 ⚫ 名前 ⚫ 住所 ⚫ メールアドレス ⚫ 電話番号 ⚫ 誕生日 ✓ 項目を並べるときは箇条書きを活用すると、並列関係が視覚的にわかりやすくなるポイント

Slide 47

Slide 47 text

おまけ 47

Slide 48

Slide 48 text

ショートケーキを説明する 48 ショートケーキは、イチゴとホイップクリームをふんだんに使った、シンプルなのに華やかなケーキだ。イチゴ好きにも、クリーム好きにもたまらない。刻んだイチゴを混ぜたホイップクリームをつなぎにして、柔らかなスポンジを何層か重ねる。さらに、その周りをホイップクリームで包み込み、イチゴを載せて飾り付ける。イチゴとホイップクリームは、お互いを引き立て合う存在だ。真っ白なホイップクリームは、イチゴの赤色をより鮮やかに映えさせる。そして甘酸っぱいイチゴは、ホイップクリームの甘さをより強く感じさせてくれる。その絶妙な組み合わせは、目にも舌にも素晴らしい。まず全体を言う魅力も沿えると、なお良いショートケーキの構成要素へと進む要素同士の関係を語る

Slide 49

Slide 49 text

チェックシート ✓ 冒頭に概要を書いていますか？ ✓ 一文一義で書いていますか？ ✓ 読者の視点で書かれていますか？ ✓ 重要なことから書かれていますか？ ✓ 文はこれ以上短くなりませんか？ ✓ 曖昧な表現はありませんか？ ✓ 係り受けは明確ですか？ ✓ 二重否定になっていませんか？ ✓ 主語や目的語と動詞の位置が離れすぎていませんか？ 49