Upgrade to Pro — share decks privately, control downloads, hide ads and more …

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

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

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

Naohiro Nakata

June 01, 2022
Tweet

More Decks by Naohiro Nakata

Other Decks in Business

Transcript

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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



    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

  18. 伝える情報を整理する
    18

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

  30. アウトラインを作る
    30

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

  47. おまけ
    47

    View Slide

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

    View Slide

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

    View Slide