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

テクニカルライティングの基本を学べます。サイボウズの新入社員向け研修資料です。業務マニュアル、報告書、仕様書、技術解説書などのドキュメントを書く機会がある方向け。
Twitter：https://twitter.com/naoh_nak
2023年度のアップデート版もあります：https://speakerdeck.com/naohiro_nakata/technicalwriting2023

Transcript

1. テクニカルライティングの基本 2022年5月17日 開運研修2022 開発本部 テクニカルコミュニケーションチーム 仲田 1
2. 2 仲田 尚央 Nakata Naohiro @naoh_nak 開発本部 テクニカルコミュニケーションチーム テクニカルライター/ローカライズ 職能マネージャー お仕事の内容： ⚫ サイボウズ製品のUIテキストを書く ⚫ 製品のマニュアルやヘルプを書く ⚫ それらを他の言語に展開する（ローカライズ）
3. テクニカルライティングは 3 読者や目的に合わせて技術をわかりやすく伝える手法です。
4. みなさんは、これから「ドキュメント」を書く機会が多くあります。 4
5. ⚫ 報告書や企画書を書く ⚫ 業務マニュアルを書く ⚫ 製品や機能の解説を書く ⚫ 作業手順書を書く ⚫ 製品の仕様書を書く ⚫ … 5
6. ドキュメントは多くの人に読まれます 6 業務マニュアル
7. 書き手の工夫で、多くの人の時間を節約できます 7 業務マニュアル
8. 書き方の方法論を学ぶことで、書き手の時間も節約できます 8 業務マニュアル
9. チームワークのために、情報共有は欠かせません。 良いドキュメントを書くことは、効率的な情報共有に繋がります。 9
10. テクニカルライティングの適用対象 ⚫ いわゆる「実用文」が求められるもの ⚫ 議事録 ⚫ 報告書 ⚫ 技術書・解説書 ⚫ 仕様書 ⚫ マニュアル・FAQ などなど 10
11. ドキュメントの前提1 - 求める情報が人によって違う 11 業務マニュアル 作業Aの手順を知りたい。 入社したばかりで何もわからん。 今度担当することになった業務Bにつ いて、一通り全部学びたい。 インストールが必要なツールを知りたい。 ・・・
12. ドキュメントの前提2 - 情報の探し方も違う 12 業務マニュアル 作業Aの手順を知りたい。 入社したばかりで何もわからん。 今度担当することになった業務Bにつ いて、一通り全部知っておきたい。 インストールが必要なツールを知りたい。 ・・・ 知りたいことが明確 知りたいことが曖昧 網羅的に知りたい
13. ドキュメントの前提3 – 一意に伝わる必要がある 13 ✕ ✕ ✕
14. ドキュメントの前提4 – 一部しか読まれない 14
15. テクニカルライティングの要素 15 Effectiveness 必要な情報を正しく得られる Satisfaction 不快さがなく、肯定的に 受け止められる Efficiency 効率よく理解できる ユーザビリティーの定義 （ISO 9241-11）から
16. それぞれの要素に対して取る手段 16 Effectiveness 必要な情報を正しく得られる Satisfaction 不快さがなく、肯定的に 受け止められる Efficiency 効率よく理解できる • 曖昧さを排し、明確に書く • できるだけ具体的に書く • 誤解なく読める文章で書く • 情報を適切に整理、構造化する • どこに何が書いてあるかをわかりやすくする • 簡潔で読みやすい文章で書く • 必要な情報だけを書く • 肯定的な表現で書く • ですます調で書く （過剰な敬語にはしない）
17. テクニカルライティングの進め方 1. 伝える情報を整理する 2. アウトラインを作る 3. わかりやすく、簡潔な文章で書く 17
18. 伝える情報を整理する 18
19. 整理の鉄則 19 概要から具体へ または 全体から部分へ
20. 20 伝えるテーマ テーマ1 テーマ1-1 テーマ1-1-1 テーマ1-1-2 テーマ1-2 テーマ2 テーマ2-1 テーマ2-2 概要 全体 具体 部分 具体例で分解 構成要素で分解
21. 書籍や文書の場合 21 伝えるテーマ テーマ1 テーマ1-1 テーマ1-1-1 テーマ1-1-2 テーマ1-2 テーマ2 テーマ2-1 テーマ2-2 章 節 項
22. Webの場合 22 伝えるテーマ テーマ1 テーマ1-1 テーマ1-1-1 テーマ1-1-2 テーマ1-2 テーマ2 テーマ2-1 テーマ2-2 カテゴリー ページ 見出し
23. 全体から部分へと分解する 23 kintone アプリ レコード フィールド コメント ビュー（一覧） アクセス権 ・・・ スペース 公開スペース 非公開スペース ゲストスペース ピープル メッセージ
24. 概要から具体へと分解する 24 スマートフォン Android Pixel Xperia Galaxy ・・・ iOS iPhone Pro Max iPhone Pro iPhone mini ・・・
25. 順に説明を展開していく 25 スマートフォン Android Pixel Xperia Galaxy ・・・ iOS iPhone Pro Max iPhone Pro iPhone mini ・・・ 段階を追って知識を付け加えて いくことが、わかりやすさに繋がる
26. 情報を適切に分解すると、読者が情報を探しやすくなる 26 スマートフォン Android Pixel Xperia Galaxy ・・・ iOS iPhone Pro Max iPhone Pro iPhone mini ・・・ 前知識がない人は、最初 から読み、興味を持った 項目へと進む 特定の知識が欲しい人は、 その項だけを読む さわりだけを知りたい人は、 概要だけを読む どこに何が書いてあるかがわかるよう、適切なタイトルと見出しを付けよう
27. 分解には複数のやり方がある 27 スマートフォン コミュニケーション ・・・ ・・・ ニュース ・・・ ・・・ 買い物 ナビ ゲーム ・・・
28. 情報整理の例 - 良いヘルプの要素を分解する ⚫ まず、良いヘルプの要素を具体化する ⚫ 要素ごとに、どうすれば満たせるかを考察し ていく 28 良いヘルプ 役に立つ ターゲットユーザーの設定 情報の収集方法 探しやすい 情報の分類 タイトルや見出しの付け方 検索最適化 わかりやすい 用語の統一 読みやすい文章の書き方 図解 正しい ・・・
29. 情報整理の例 - 説明の構成に反映する 29 誰に何を伝えるかを整理する 『ヘルプサイトの作り方』 章構成 良いヘルプ 役に立つ ターゲットユーザーの設定 情報の収集方法 探しやすい 情報の分類 タイトルや見出しの付け方 検索最適化 わかりやすい 用語の統一 読みやすい文章の書き方 図解 正しい ・・・ ユーザーの使い方を意識して構成を設計する ユーザーの動線からナビゲーションを設計する スタイルガイドと用語集を準備する 記事を書く - 文章と図解のテクニック ・・・
30. アウトラインを作る 30
31. 記事で伝える情報を書き出す テーマ： kintoneでアプリを開発する方法を解説する 伝えることを書き出した例： ⚫ アプリ開発を開始する前に必要な準備 ⚫ 開発中のアプリを保存し、中断する方法 ⚫ 保存したアプリを開いて、アプリ開発を再開する方法 ⚫ 簡単なアプリを例にしたアプリ開発手順 ⚫ アプリのアイコンの作り方 ⚫ 開発したアプリに機能を追加する方法 ⚫ エラーへの対処方法 31 ✓ この段階では、順番や言葉の表現などの 細かいことは気にしない ✓ 情報を漏れなく洗い出すことを重視 ポイント
32. 書き出した情報を整理する 伝える情報を整理した例： ⚫ アプリ開発の全体の流れ ⚫ 簡単なアプリを例にしたアプリ開発手順 ⚫ アプリ開発を開始する前の準備 ⚫ 開発手順 ⚫ アプリのアイコンの作り方 ⚫ 開発中のアプリを保存し、中断する方法 ⚫ 保存したアプリを開き、アプリ開発を再開する方法 ⚫ エラーへの対処方法 ⚫ 開発したアプリに機能を追加する方法 32 ✓ まず概要を述べる ✓ 読者がどのように情報を探そうとするかを 意識して、情報を整理する ✓ どのタイミングで必要になる情報かを意識 して、項目を並び替える ポイント
33. 見出しを決める 見出し構造の例： ⚫ アプリ開発の流れ ⚫ アプリを開発しよう ⚫ 開発を始める前に ⚫ ◦◦◦を設定しよう ⚫ ◦◦◦を設定しよう ⚫ ◦◦◦を設定しよう ⚫ アプリのアイコンを作ろう ⚫ アプリ開発を中断する場合 ⚫ アプリ開発を再開するには ⚫ アプリ開発中にエラーになったら ⚫ アプリに機能を追加しよう 33 ✓ 読者が次の情報を読み取れる言葉にすること を意識する： ⚫ 見出しに続く本文に何が書かれているか ⚫ どのようなときに読む必要があるのか ポイント
34. わかりやすく、簡潔な文章で書く 34
35. 書くときの心構え ⚫ 読者の行動をイメージしながら書く どんな人が、どんな情報を、どのように探すか ⚫ （自分ではなく）読者の視点で書く ⚫ 簡潔に、できるだけ短文で書く ⚫ 重要なことから書く 35
36. 重要なことから書く 36 ⚫ Before システムを正常に起動できなくなる恐れがあるので、アッ プデート中は電源を切らないでください。 ⚫ After アップデート中は電源を切らないでください。システムを 正常に起動できなくなります。 ✓ ドキュメントは、一部しか読まれないことを 前提に書く ✓ 情報に優先度を付けて、優先度が高い ことを先に書く ポイント
37. 一文一義で書く ⚫ Before サイボウズ Officeは、クラウド型グループウェアで、情報 を共有する各種機能、メッセージ機能やワークフロー機 能などを備え、使いやすさが特長です。 ⚫ After サイボウズ Officeは、クラウド型グループウェアです。情 報を共有する各種機能、メッセージ機能やワークフロー 機能などを備えています。使いやすさがサイボウズ Officeの特長です。 37 ✓ 1つの文には、1つの事柄だけを書く ✓ 1文に複数の事柄が詰め込まれていると、 内容を整理しながら読まなくてはならなく なる ポイント
38. 簡潔に書く 38 ⚫ Before ほかのユーザーの連絡先を確認でき、また、ほかのユーザーに メッセージを送ることもできます。 ⚫ After ほかのユーザーの連絡先を確認できます。また、ほかのユー ザーにメッセージを送ることもできます。 ⚫ さらに改善 ほかのユーザーの連絡先を確認できます。また、ほかのユー ザーにメッセージを送ることもできます。 ✓ 簡潔、短くを常に意識する ✓ 「したがって」「または」などの接続詞も、不 要なことが多い ポイント
39. 読者の視点で書く 39 ⚫ Before ニュースレターに登録いただくと、製品のアップデート情報 をメールでお送りします。 ⚫ After ニュースレターに登録すると、製品のアップデート情報を メールで受け取れます。 ✓ 読者の視点で書くことが、読みやすさと、 わかりやすさに繋がる ✓ システムが主語になっていると、自分視点 に置き換えながら読まなくてはならなくなる ポイント
40. 能動態と受動態を使い分ける 40 ⚫ Before [削除]をクリックすると、すべてのデータを削除します。 ⚫ After [削除]をクリックすると、すべてのデータが削除されます。 ✓ 読者の視点で書くと、読者の操作は能動 態、システムの動作は受動態になる ポイント 能動態 受動態
41. できるだけ具体的に書く 41 ⚫ Before メール通知の設定を確認してください。 間隔を少しだけ空ける必要があります。 ⚫ After メール通知が有効になっていることを確認してください。 3～5mmの間隔が必要です。 ✓ 曖昧な表現は、書き手の意図通りに伝 わらない ✓ 具体的に書く努力を ポイント
42. 肯定形で書く 42 ⚫ Before 5名以上の予約は受け付けられません。 ⚫ After 4名まで予約できます。 ✓ 否定表現は、理解に時間がかかるだけで なく、ネガティブな印象を招く ✓ 肯定形に書き換えることで、簡潔でポジ ティブな印象になる ポイント
43. 二重否定を使わない 43 ⚫ Before ファイルA以外は削除しないでください。 ⚫ After ファイルAだけを削除してください。 ✓ 否定表現は、1つの文に1つまで ✓ 二重否定は文章をわかりづらくし、読者 の混乱を招く ポイント
44. 係り受けを明確にする 44 ⚫ Before 消毒液Aのように刺激の強くない消毒液を使ってください。 ⚫ After 消毒液Aのような、刺激の強くない消毒液を使ってくださ い。 または 消毒液Aのように刺激の弱い消毒液を使ってください。 ✓ 係り受けが不明確な文章は、まったく逆 の意味に受け取られることがある ポイント 消毒液Aは使って良いの？
45. 主語や目的語と、述語を近づける 45 ⚫ Before データは、自動同期を無効にした場合は手動で同期し ない限りバックアップされません。 ⚫ After 自動同期を無効にした場合は、手動で同期しない限り データはバックアップされません。 ✓ 文が長くなるときは、主語や目的語と述 語を近づけると読みやすくなる ポイント
46. 列記には箇条書きを使う 46 ⚫ Before 名前、住所、メールアドレス、電話番号、および誕生日の入力は任 意です。 ⚫ After 次の項目の入力は任意です。 ⚫ 名前 ⚫ 住所 ⚫ メールアドレス ⚫ 電話番号 ⚫ 誕生日 ✓ 項目を並べるときは箇条書きを活用する と、並列関係が視覚的にわかりやすくなる ポイント
47. おまけ 47
48. ショートケーキを説明する 48 ショートケーキは、イチゴとホイップクリームをふんだんに使った、シンプルなのに 華やかなケーキだ。イチゴ好きにも、クリーム好きにもたまらない。 刻んだイチゴを混ぜたホイップクリームをつなぎにして、柔らかなスポンジを何 層か重ねる。さらに、その周りをホイップクリームで包み込み、イチゴを載せて 飾り付ける。 イチゴとホイップクリームは、お互いを引き立て合う存在だ。真っ白なホイップ クリームは、イチゴの赤色をより鮮やかに映えさせる。そして甘酸っぱいイチゴ は、ホイップクリームの甘さをより強く感じさせてくれる。その絶妙な組み合わ せは、目にも舌にも素晴らしい。 まず全体を言う 魅力も沿えると、なお良い ショートケーキの 構成要素へと進む 要素同士の 関係を語る
49. チェックシート ✓ 冒頭に概要を書いていますか？ ✓ 一文一義で書いていますか？ ✓ 読者の視点で書かれていますか？ ✓ 重要なことから書かれていますか？ ✓ 文はこれ以上短くなりませんか？ ✓ 曖昧な表現はありませんか？ ✓ 係り受けは明確ですか？ ✓ 二重否定になっていませんか？ ✓ 主語や目的語と動詞の位置が離れすぎていませんか？ 49