書く前に立ち止まって考えよう！「伝える情報を整理する」ということ

書き始める前に、情報をきちんと分解して整理しよう、というお話です。
「DevRel Meetup in Tokyo #76 〜分かりやすいドキュメントを学ぼう〜」のプレゼンスライド。
https://devrel.connpass.com/event/250808/
内容の一部は「テクニカルライティングの基本」と同じです。
https://speakerdeck.com/naohiro_nakata/technicalwriting

Transcript

1. 書く前に立ち止まって考えよう！
   「伝える情報を整理する」ということ
   1
   DevRel Meetup in Tokyo #76
   

   View Slide

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

   View Slide

3. 3
   和氣 一成
   開発本部 テクニカルコミュニケーションチーム
   お仕事の内容：
    製品のマニュアルやヘルプを書く
   Issei Wake
   経歴
    サイボウズに2018年 新卒入社
    製品サポートセンター → 今年2月に異動
   （駆け出しライターです。お手柔らかにお願いします）
   

   View Slide

4. これからお話すること
   4
   前半：テクニカルライティングってなに？
   後半：書き始める前に、情報をきちんと分解して整理しよう
   

   View Slide

5. 前半：テクニカルライティングってなに？
   5
   

   View Slide

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

   View Slide

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

   View Slide

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

   View Slide

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

   View Slide

10. 書き方の方法論を学ぶことで、書き手の時間も節約できます
    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. テクニカルライティングの進め方
    1. 伝える情報を整理する
    2. アウトラインを作る
    3. わかりやすく、簡潔な文章で書く
    18
    このセッションのテーマ
    

    View Slide

19. 後半：伝える情報を整理する
    19
    

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

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

    View Slide

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

    View Slide

29. 情報の適切な分解って？
    29
    NG：きれいに分解できる
    OK：読者の目的に合わせる
    

    View Slide

30. 30
    スマートフォンを
    買う
    Android
    Pixel
    Xperia
    Galaxy
    ・・・
    iOS
    iPhone Pro Max
    iPhone Pro
    iPhone mini
    ・・・
    初めてのスマートフォン
    どれを選べばいいの？
    種類が多すぎて…
    スマートフォンをOSや機種の具体例で分解
    読者
    

    View Slide

31. スマートフォンを
    使いこなす
    コミュニケーション
    ・・・
    ・・・
    ニュース
    ・・・
    ・・・
    買い物
    ナビ
    ゲーム
    ・・・
    31
    スマートフォン買ったよ！
    使いこなしたい
    スマートフォンを用途の具体例で分解
    読者
    

    View Slide

32. スマートフォン
    スマートフォンを買う
    Android
    iOS
    スマートフォンを
    使いこなす
    コミュニケーション
    ニュース
    買い物
    ナビ
    ゲーム
    32
    分解方法は、サブテーマごとに異なってもいい
    ただし、同階層での混在はダメ
    OSや機種の具体例で分解
    用途の具体例で分解
    

    View Slide

33. スマートフォン
    スマートフォンを
    買う
    Android
    iOS
    スマートフォンを
    使いこなす
    コミュニケーション
    ニュース
    買い物
    ナビ
    ゲーム
    スマートフォンを
    メンテナンスする
    デバイス
    ストレージ
    バッテリー
    33
    • 時系列で
    • 重要なことから
    • 情報のニーズが大きいものから
    テーマを並べる
    

    View Slide

34. 読者の目的
    を考える
    情報をどう分解するか
    を考える
    情報をどう並べるか
    を考える
    34
    

    View Slide

35. まとめ
     書き始める前に、情報をきちんと分解して整理しよう
     分解には、2つの方法があります
     具体例で分解する
     構成要素で分解する
     どの方法での分解が適切かは、読者の目的で決まります
     分解してできた要素に沿って、徐々に知識を付け加えていくことが、わか
    りやすさに繋がります
    35
    

    View Slide