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

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

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

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

Naohiro Nakata

June 22, 2023
Tweet

More Decks by Naohiro Nakata

Other Decks in Business

Transcript

  1. 2 仲⽥ 尚央 Nakata Naohiro @naoh_nak テクニカルライターとローカライズの職能マネージャー 都⽴産業技術⾼専 ⾮常勤講師 お仕事の内容︓

    l サイボウズ製品のUIテキストを書く l 製品のマニュアルやヘルプを書く l それらを他の⾔語に展開する(ローカライズ)
  2. ドキュメントの前提2 - 情報の探し⽅も違う 13 業務マニュアル 作業Aの⼿順を知りたい。 ⼊社したばかりで何もわからん。 今度担当することになった業務Bにつ いて、⼀通り全部知っておきたい。 インストールが必要なツールを知りたい。

    ・・・ 知りたいことが明確 知りたいことが曖昧 網羅的に知りたい • 求める情報が違えば、情報の探し⽅も違う • 読み⼿がどのように情報を探すかを意識する • 対象読者を絞ることも有効
  3. それぞれの要素に対して取る⼿段 17 Effectiveness 必要な情報を正しく得られる Satisfaction 不快さがなく、肯定的に 受け⽌められる Efficiency 効率よく理解できる •

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

    曖昧さを排し、明確に書く • できるだけ具体的に書く • 誤解なく読める⽂章で書く • 情報を適切に整理、構造化する • どこに何が書いてあるかをわかりやすくする • 重要なことから書く • 簡潔で読みやすい⽂章で書く • 必要な情報だけを書く • 肯定的な表現で書く • ですます調で書く (過剰な敬語にはしない) テクニカルライティングにより、“ユーザビリティーの⾼いドキュメント”を書けるようになる
  5. ドキュメントの階層 ドキュメントは階層構造が基本 l 1つのドキュメントで、1つのテーマを l 1つの⾒出しで、1つのサブテーマを l 1つの段落で、1つのトピックを 21 メインテーマ

    ⾒出し トピック=段落 トピック=段落 トピック=段落 ⾒出し トピック=段落 トピック=段落 トピック=段落 サブテーマ サブテーマ 伝える情報を階層構造に整理する
  6. 全体から部分へと分解する 26 スマートフォン パネル タッチパネル 液晶パネル CPU メモリー ネットワークモジュール LANモジュール

    Bluetooth センサー 加速度センサー ジャイロセンサー 近接センサー ・・・ ハードウェアであれば構成部品で、ソフトウェアであれば構成機能で分解される
  7. 順に説明を展開していく 28 スマートフォン Android スマートフォン Pixel Xperia Galaxy ・・・ iPhone

    iPhone Pro Max iPhone Pro iPhone mini ・・・ 段階を追って知識を付け加えて いくことが、わかりやすさに繋がる
  8. 情報を適切に分解すると、読者が情報を探しやすくなる 29 スマートフォン Android スマートフォン Pixel Xperia Galaxy ・・・ iPhone

    iPhone Pro Max iPhone Pro iPhone mini ・・・ 前知識がない⼈は、最初 から読み、興味を持った 項⽬へと進む 特定の知識が欲しい⼈は、 その項だけを読む さわりだけを知りたい⼈は、 概要だけを読む どこに何が書いてあるかがわかるよう、適切なタイトルと⾒出しを付けよう
  9. 31 スマートフォンを 買う Android スマートフォン Pixel Xperia Galaxy ・・・ iPhone

    iPhone Pro Max iPhone Pro iPhone mini ・・・ 初めてのスマートフォン どれを選べばいいの︖ 種類が多すぎて… スマートフォンをOSや機種の具体例で分解
  10. スマートフォンを 使いこなす コミュニケーション ・・・ ・・・ ニュース ・・・ ・・・ 買い物 ナビ

    ゲーム ・・・ 32 スマートフォン買ったよ︕ 使いこなしたい スマートフォンを⽤途の具体例で分解
  11. スマートフォン スマートフォンを買う Android スマートフォン iOS スマートフォンを 使いこなす コミュニケーション ニュース 買い物

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

    買い物 ナビ ゲーム スマートフォンを メンテナンスする デバイス ストレージ バッテリー 34 • 重要なことから • 既知から未知へ • 情報のニーズが⼤きいものから • 時系列で のいずれかで要素を並べる
  13. 情報整理の例 - 良いヘルプの要素を分解する l まず、良いヘルプの要素を具体化する l 要素ごとに、どうすれば満たせるかを考察し ていく 35 良いヘルプ

    役に⽴つ ターゲットユーザーの設定 情報の収集⽅法 探しやすい 情報の分類 タイトルや⾒出しの付け⽅ 検索最適化 わかりやすい ⽤語の統⼀ 読みやすい⽂章の書き⽅ 図解 正しい ・・・
  14. 情報整理の例 - 説明の構成に反映する 36 誰に何を伝えるかを整理する 『ヘルプサイトの作り⽅』 章構成 良いヘルプ 役に⽴つ ターゲットユーザーの設定

    情報の収集⽅法 探しやすい 情報の分類 タイトルや⾒出しの付け⽅ 検索最適化 わかりやすい ⽤語の統⼀ 読みやすい⽂章の書き⽅ 図解 正しい ・・・ ユーザーの使い⽅を意識して構成を設計する ユーザーの動線からナビゲーションを設計する スタイルガイドと⽤語集を準備する 記事を書く - ⽂章と図解のテクニック ・・・
  15. アウトラインとは l 物事のあらまし・⼤筋・概略 l ドキュメントにおけるアウトラインとは、章・節・項などの⾒出しを 階層的に設定、表⽰したもの l 2つの役割を持つ︓ l 説明の流れをあらかじめ読み⼿に掴ませ、⼼の準備をさせる役割

    l 必要とする情報がどこに書かれているか、探しやすくする役割 38 • 概要 • 背景と⽬的 • 調査の⽅法 • データの収集 • データの分析 • 結果と考察 • 結論とまとめ 例︓レポートのアウトライン
  16. 記事の基本構成 l タイトルで、その記事のテーマを伝える l リード⽂で、これから何を述べるのかを伝える l 次に、これから述べることの概要や全体像を伝える l さらに、サブテーマごとの詳細へと展開していく 39

    タイトル(≒テーマ) 概要・全体像 ⾒出し(任意) ⾒出し サブテーマ1 ⾒出し サブテーマ2 リード⽂ ü 1つの記事の中でも階層構造をとる ポイント
  17. 伝える情報を分解する 41 スマートフォン 種類 Android iPhone ⽤途 コミュニケーション ウェブブラウジング ・・・

    機能 インターネット 写真やビデオの撮影 メディアの再⽣ アプリによる追加機能 通話 センシング 「スマートフォンとは何か」 を伝えてみよう︕
  18. 分解した要素を並び替える 42 スマートフォン 機能 通話 インターネット 写真やビデオの撮影 メディアの再⽣ センシング アプリによる追加機能

    ⽤途 コミュニケーション ウェブブラウジング ・・・ 種類 Android iPhone • 重要なことから • 既知から未知へ • 情報のニーズが⼤きいものから • 時系列で のいずれかに並び替える
  19. ⾒出しを付ける要素を選ぶ 43 スマートフォン 機能 通話 インターネット 写真やビデオの撮影 メディアの再⽣ センシング アプリによる追加機能

    ⽤途 コミュニケーション ウェブブラウジング ・・・ 種類 Android iPhone 内容が少なそうなので、 「概要」に含める 内容が多そうなので、 ⾒出しを付ける
  20. 要素をアウトラインに反映する 44 スマートフォン 機能 通話 インターネット 写真やビデオの撮影 メディアの再⽣ センシング アプリによる追加機能

    ⽤途 コミュニケーション ウェブブラウジング ・・・ 種類 Android iPhone アウトライン l スマートフォンの概要 l スマートフォンの⽤途 l コミュニケーション l ウェブブラウジング l ・・・ l スマートフォンの種類 l Android l iPhone
  21. ⾒出しを決める 45 スマートフォン 機能 通話 インターネット 写真やビデオの撮影 メディアの再⽣ センシング アプリによる追加機能

    ⽤途 コミュニケーション ウェブブラウジング ・・・ 種類 Android iPhone ü ⾒出しを⾒るだけで読者が次の情報を読み 取れる⾔葉にする︓ l 説明の流れ l ⾒出しに続く本⽂に何が書かれているか l どのようなときに読む必要があるのか アウトライン l スマートフォンとは l スマートフォンの便利な活⽤⽅法 l 友⼈や家族と会話する l インターネットで情報を得る l ・・・ l スマートフォンの種類 l Androidスマートフォン l iPhone
  22. トピックを意識する l ⽂章を書き始める前に、段落単位で⽂章 の構成を組む l 1つの段落が1つのトピック(話題)になる l 1つの段落は3⽂〜8⽂程度 l Webでは2⽂〜5⽂程度が⽬安

    l 短過ぎると、主張の根拠が不⾜する l ⻑過ぎると、読みづらくなる 47 トピック1 ⾒出し トピック2 トピック3 ⾒出し トピック1 ・・・
  23. トピックを意識する効果 l 読み⼿ l 順序⽴てて話題が進むので、頭に⼊りやすい l 段落単位で読み⾶ばしができる l 書き⼿ l

    書くべきトピックが決まっていると、書きやすい l 情報の過不⾜が視覚的にわかる 48
  24. 伝える情報の要素にトピックを割り当てる 49 スマートフォンの機能 通話 インターネット 写真やビデオの撮影 メディアの再⽣ センシング アプリによる追加機能 概要

    インターネットのトピック 写真や動画の撮影のトピック センシングのトピック アプリによる機能追加のトピック 段落構成 • 内容が多い要素、重要な要素 にトピックを割り当てる • それ以外は概要に含める
  25. それぞれのトピックを展開する スマートフォンは、携帯電話とコンピューターの機能を併せ持つ携帯機器です。⼀般的には、タッチスクリーンディスプレイを備 え、通話、インターネット、写真や動画の撮影、⾳楽や動画の再⽣、各種センサーによる周辺情報の取得などの機能を提 供します。また、アプリケーション(アプリ)をインストールして機能を追加することもできます。 スマートフォンは、インターネットへの接続が可能で、モバイルデータネットワークやWi-Fiを使⽤して情報のやり取りができます。 ⽇常⽣活の中で場所を問わず情報にアクセスすることを可能にし、ウェブブラウジング、メディアの視聴、ソーシャルメディアの 利⽤、オンラインショッピング、ビジネス活動など、さまざまな⽬的に使⽤されています。 スマートフォンは、写真や動画の撮影機器としても広く使⽤されています。撮った写真を、スマートフォンを使ってその場で加 ⼯したり、友⼈に共有したり、ソーシャルメディアに投稿したりすることも、撮影の楽しみ⽅の⼀つになっています。 さらに、スマートフォンにはGPSやさまざまなセンサーが組み込まれており、加速度計、ジャイロスコープ、電⼦コンパス、近接

    センサー、光センサーなどがあります。これらから得られる周辺情報により、スマートフォンは、地図やナビゲーションを代表例と した、⽇常⽣活を⽀援するさまざまな機能を提供します。 50 トピック 概要 インターネット 写真や動画の撮影 センシング
  26. トピックの展開 トピックを展開する代表的なパターン︓ l 詳細を述べる 「つまり、〜ということです。」 l 具体例を挙げる 「たとえば、〜があります。」 l 理由を述べる

    「その理由は、〜です。」 l データを出す 「次のデータは、〜を⽰しています。」 51 スマートフォンは、インターネットへの接続が可能で、モバイル データネットワークやWi-Fiを使⽤して情報のやり取りができます。 ⽇常⽣活の中で場所を問わず情報にアクセスすることを可能 にし、ウェブブラウジング、メディアの視聴、ソーシャルメディアの 利⽤、オンラインショッピング、ビジネス活動など、さまざまな⽬的 に使⽤されています。 主題 詳細
  27. 並列の情報は同じ表現で書く 52 Androidスマートフォンは、Google社が開発したAndroidというOSを搭載したスマートフォンです。カスタマイズ性が⾼く、 利⽤者はホーム画⾯にアプリやウィジットなどを⾃由に配置できます。また、Googleのサービスとの統合が強く、Googleマッ プやGoogleカレンダー、Gmailなどのアプリがスマートフォンとシームレスに連携します。多くのメーカーが、さまざまな特⾊を持 つAndroidスマートフォンを幅広い価格帯で販売しているため、利⽤者が⾃分の好みや予算に合わせて選択できることも 魅⼒です。 iPhoneは、Apple社が開発し販売するスマートフォンです。iPhoneはシンプルで洗練されたデザインを特⻑とするiOSと いうOSを搭載し、ハードウェアとの最適化された統合により、⾼いパフォーマンスと優れた利⽤体験を提供します。また、アプ リストアを通してiPhoneに配信されるアプリには厳格な審査基準があり、マルウェアや不正なアプリのリスクを低減するための

    セキュリティに重点が置かれています。iOSのアップデートを通じて新機能やセキュリティーの改善が⻑期に渡って頻繁に提供 されることも魅⼒です。 トピック Androidスマートフォン の特徴 iPhoneの特徴 並列の情報は同じ表現で書くと、⽂章の展開を予測してから読めるようになる
  28. 重要なことから書く 55 l Before(理由 → 主張の順) 外出先から空き時間にメールを確認したり、オンラインミーティ ングに参加したり、報告書を提出したりできるようになるので、 業務でスマートフォンを活⽤することが、⽣産性の向上に繋が ります。

    l After(主張 → 理由の順) 業務でスマートフォンを活⽤することが、⽣産性の向上に繋が ります。外出先から空き時間にメールを確認したり、オンライン ミーティングに参加したり、報告書を提出したりできるようにな るからです。 ü ドキュメントは、⼀部しか読まれないことを 前提に書く ü 情報に優先度を付けて、優先度が⾼い ことを先に書く ü たとえば、主張(伝えたいこと)は理由よ りも前に書く ポイント
  29. 読者の視点で書く 56 l Before ニュースレターに登録いただくと、アプリのアップデート情報を メールでお送りします。 l After ニュースレターに登録すると、アプリのアップデート情報をメール で受け取れます。

    ü 読者の視点で書くことが、読みやすさと、 わかりやすさに繋がる ü 書き⼿やシステムが主語になっていると、 ⾃分視点に置き換えながら読まなくては ならなくなる ポイント
  30. ⼀⽂を短くする 59 l Before スマートフォンで写真を撮ることができ、また、撮った写真をその 場で友⼈に共有することもできます。 l After スマートフォンで写真を撮ることができます。また、撮った写真を その場で友⼈に共有することもできます。

    l さらに改善 スマートフォンで写真を撮ることができます撮れます。また、 撮った写真をその場で友⼈に共有することもできます。 ü 簡潔、短くを常に意識する ü 「したがって」「また」などの接続詞も、不要 なことが多い ü 「(⽂の)わかりやすさと⻑短とは本質的 には関係がない」(『⽇本語の作⽂技術』 12刷, 本 ⽥勝⼀, P.194)が、書き慣れていない⼈は 「1⽂を短く」を常に意識すべき ポイント
  31. 修飾する側とされる側を近づける 60 l Before スマートフォンは、GPSや電⼦コンパスなどから得られる情報 をもとにして、Googleマップのような専⽤アプリを通じて、ナビ ゲーションの機能を提供します。 l After GPSや電⼦コンパスなどから得られる情報をもとにして、

    Googleマップのような専⽤アプリを通じて、スマートフォンは ナビゲーションの機能を提供します。 ü ⽂が⻑くなるときは、修飾する側(主語 や⽬的語)と 修飾される側(述語)を 近づけると、読みやすくなる ポイント
  32. 読点のパターン 63 例 説明 メーカーにより、提供されるアップデートの頻度は異なります。 係り受けを明確にするために打つ スマートフォンには、加速度計、ジャイロスコープや、近接セン サーなどのセンサーが組み込まれています。 並列関係を明確にするために打つ 最新のアップデートを適⽤することで、悪意のある攻撃やデータ

    漏洩などのリスクを減らすことができます。 理由・条件・⽬的などを明確にするために打つ スマートフォンは、社会的なつながりや情報へのアクセスを容易 にし、⽇常⽣活のさまざまな場⾯で利⽤されています。 節の区切りを明確にするために打つ しかし、近年ではスマホ中毒と呼ばれる依存症の問題が指摘さ れています。 接続詞の後ろに打つ(接続関係を強調した い場合)
  33. 並列の情報には箇条書きを使う 64 l Before スマートフォンには、加速度計、ジャイロスコープ、近接セン サーや、光センサーなどのセンサーが組み込まれています。 l After スマートフォンには、次のようなセンサーが組み込まれています。 l

    加速度計 l ジャイロスコープ l 近接センサー l 光センサー ü 並列の情報を並べるときは、箇条書きを 活⽤すると、並列関係が視覚的にわかり やすくなる ポイント
  34. できるだけ具体的に書く 65 l Before 例1︓ スマートフォンの⾳量の設定を確認してください。 例2︓ iPhoneは簡単に使えます。 l After

    例1︓ スマートフォンが消⾳の設定になっていないことを確認 してください。 例2︓ iPhoneは、アイコンベースのホーム画⾯やタッチによる 操作など、使い⽅が直感的に理解できるように設計 されています。 ü 曖昧な表現は、書き⼿の意図通りに伝 わらない ü 具体的に書く努⼒を ポイント
  35. 肯定形で書く 66 l Before ソフトウェアのアップデートは放置したままにしないでください。 l After ソフトウェアのアップデートはなるべく早めに適⽤してください。 ü 否定表現は意味を曖昧にする

    ü 肯定形で表現できる場合は、なるべく肯定 形を使う ü 禁⽌事項を伝える場合は、敢えて否定形 で書くのも良い 例︓電源を切らないでください ポイント
  36. 肯定形で書くと、印象も変わる 67 l Before 5名以上の予約は受け付けられません。 l After 4名まで予約できます。 ü 否定表現は、理解に時間がかかるだけで

    なく、ネガティブな印象を招く ü 肯定形に書き換えることで、簡潔でポジ ティブな印象になる ポイント
  37. チェックシート ü 冒頭に概要を書いていますか︖ ü ⼀⽂⼀義で書いていますか︖ ü 読者の視点で書いていますか︖ ü 重要なことから書いていますか︖ ü

    ⽂はこれ以上短くなりませんか︖ ü 曖昧な表現はありませんか︖ ü 係り受けは明確ですか︖ ü 否定⽂は肯定形で書けませんか︖ ü 修飾する側とされる側が離れ過ぎていませんか︖ 69