Share
Embed
テクニカルライティングの基本 2023年版
テクニカルライティングの基本を学べます。業務マニュアル、報告書、仕様書、技術解説書などのドキュメントを書く機会がある方向け。サイボウズの2023年度 新入社員向け研修の資料です。
本資料をもとにした書籍も発売中です:https://amzn.asia/d/2hQNEk2
Twitter:https://twitter.com/naoh_nak
2022年版(初版):https://speakerdeck.com/naohiro_nakata/technicalwriting
Naohiro Nakata
June 22, 2023
Transcript
69 slides
-
2 仲⽥ 尚央 Nakata Naohiro @naoh_nak テクニカルライターとローカライズの職能マネージャー 都⽴産業技術⾼専 ⾮常勤講師 お仕事の内容︓
l サイボウズ製品のUIテキストを書く l 製品のマニュアルやヘルプを書く l それらを他の⾔語に展開する(ローカライズ) -
本講の流れ 1. テクニカルライティングの基本的な考え⽅を知る 2. 情報を適切に整理するためのコツを知る 3. ⽂章の構成を組むためのコツを知る 4. わかりやすい⽂章を書くためのコツを知る 3
ü 本講では、⽂章の書き⽅だけでなく、情報をどう整理するかにも重点を置いています。 -
l 報告書や企画書を書く l 業務マニュアルを書く l 製品や機能の解説を書く l 作業⼿順書を書く l 製品の仕様書を書く
l 技術ブログを書いたり l … 6 -
テクニカルライティングの適⽤対象 l いわゆる「実⽤⽂」が求められるもの l 議事録 l 報告書 l 技術書・解説書 l
仕様書 l マニュアル・FAQ l 技術ブログ などなど 11 -
ドキュメントの前提2 - 情報の探し⽅も違う 13 業務マニュアル 作業Aの⼿順を知りたい。 ⼊社したばかりで何もわからん。 今度担当することになった業務Bにつ いて、⼀通り全部知っておきたい。 インストールが必要なツールを知りたい。
・・・ 知りたいことが明確 知りたいことが曖昧 網羅的に知りたい • 求める情報が違えば、情報の探し⽅も違う • 読み⼿がどのように情報を探すかを意識する • 対象読者を絞ることも有効 -
それぞれの要素に対して取る⼿段 17 Effectiveness 必要な情報を正しく得られる Satisfaction 不快さがなく、肯定的に 受け⽌められる Efficiency 効率よく理解できる •
曖昧さを排し、明確に書く • できるだけ具体的に書く • 誤解なく読める⽂章で書く • 情報を適切に整理、構造化する • どこに何が書いてあるかをわかりやすくする • 重要なことから書く • 簡潔で読みやすい⽂章で書く • 必要な情報だけを書く • 肯定的な表現で書く • ですます調で書く (過剰な敬語にはしない) -
それぞれの要素に対して取る⼿段 18 Effectiveness 必要な情報を正しく得られる Satisfaction 不快さがなく、肯定的に 受け⽌められる Efficiency 効率よく理解できる •
曖昧さを排し、明確に書く • できるだけ具体的に書く • 誤解なく読める⽂章で書く • 情報を適切に整理、構造化する • どこに何が書いてあるかをわかりやすくする • 重要なことから書く • 簡潔で読みやすい⽂章で書く • 必要な情報だけを書く • 肯定的な表現で書く • ですます調で書く (過剰な敬語にはしない) テクニカルライティングにより、“ユーザビリティーの⾼いドキュメント”を書けるようになる -
ドキュメントの階層 ドキュメントは階層構造が基本 l 1つのドキュメントで、1つのテーマを l 1つの⾒出しで、1つのサブテーマを l 1つの段落で、1つのトピックを 21 メインテーマ
⾒出し トピック=段落 トピック=段落 トピック=段落 ⾒出し トピック=段落 トピック=段落 トピック=段落 サブテーマ サブテーマ 伝える情報を階層構造に整理する -
23 伝えるテーマ テーマ1 テーマ1-1 テーマ1-1-1 テーマ1-1-2 テーマ1-2 テーマ2 テーマ2-1 テーマ2-2
概要 全体 具体 部分 具体例で分解 構成要素で分解 -
Webの場合 25 伝えるテーマ テーマ1 テーマ1-1 テーマ1-1-1 テーマ1-1-2 テーマ1-2 テーマ2 テーマ2-1
テーマ2-2 カテゴリー ページ ⾒出し -
全体から部分へと分解する 26 スマートフォン パネル タッチパネル 液晶パネル CPU メモリー ネットワークモジュール LANモジュール
Bluetooth センサー 加速度センサー ジャイロセンサー 近接センサー ・・・ ハードウェアであれば構成部品で、ソフトウェアであれば構成機能で分解される -
概要から具体へと分解する 27 スマートフォン Android スマートフォン Pixel Xperia Galaxy ・・・ iPhone
iPhone Pro Max iPhone Pro iPhone mini ・・・ -
順に説明を展開していく 28 スマートフォン Android スマートフォン Pixel Xperia Galaxy ・・・ iPhone
iPhone Pro Max iPhone Pro iPhone mini ・・・ 段階を追って知識を付け加えて いくことが、わかりやすさに繋がる -
情報を適切に分解すると、読者が情報を探しやすくなる 29 スマートフォン Android スマートフォン Pixel Xperia Galaxy ・・・ iPhone
iPhone Pro Max iPhone Pro iPhone mini ・・・ 前知識がない⼈は、最初 から読み、興味を持った 項⽬へと進む 特定の知識が欲しい⼈は、 その項だけを読む さわりだけを知りたい⼈は、 概要だけを読む どこに何が書いてあるかがわかるよう、適切なタイトルと⾒出しを付けよう -
31 スマートフォンを 買う Android スマートフォン Pixel Xperia Galaxy ・・・ iPhone
iPhone Pro Max iPhone Pro iPhone mini ・・・ 初めてのスマートフォン どれを選べばいいの︖ 種類が多すぎて… スマートフォンをOSや機種の具体例で分解 -
スマートフォンを 使いこなす コミュニケーション ・・・ ・・・ ニュース ・・・ ・・・ 買い物 ナビ
ゲーム ・・・ 32 スマートフォン買ったよ︕ 使いこなしたい スマートフォンを⽤途の具体例で分解 -
スマートフォン スマートフォンを買う Android スマートフォン iOS スマートフォンを 使いこなす コミュニケーション ニュース 買い物
ナビ ゲーム 33 分解⽅法は、サブテーマごとに異なってもいい ただし、同じ枝の同階層での混在はダメ OSや機種の具体例で分解 ⽤途の具体例で分解 -
スマートフォン スマートフォンを 買う Android スマートフォン iPhone スマートフォンを 使いこなす コミュニケーション ニュース
買い物 ナビ ゲーム スマートフォンを メンテナンスする デバイス ストレージ バッテリー 34 • 重要なことから • 既知から未知へ • 情報のニーズが⼤きいものから • 時系列で のいずれかで要素を並べる -
情報整理の例 - 良いヘルプの要素を分解する l まず、良いヘルプの要素を具体化する l 要素ごとに、どうすれば満たせるかを考察し ていく 35 良いヘルプ
役に⽴つ ターゲットユーザーの設定 情報の収集⽅法 探しやすい 情報の分類 タイトルや⾒出しの付け⽅ 検索最適化 わかりやすい ⽤語の統⼀ 読みやすい⽂章の書き⽅ 図解 正しい ・・・ -
情報整理の例 - 説明の構成に反映する 36 誰に何を伝えるかを整理する 『ヘルプサイトの作り⽅』 章構成 良いヘルプ 役に⽴つ ターゲットユーザーの設定
情報の収集⽅法 探しやすい 情報の分類 タイトルや⾒出しの付け⽅ 検索最適化 わかりやすい ⽤語の統⼀ 読みやすい⽂章の書き⽅ 図解 正しい ・・・ ユーザーの使い⽅を意識して構成を設計する ユーザーの動線からナビゲーションを設計する スタイルガイドと⽤語集を準備する 記事を書く - ⽂章と図解のテクニック ・・・ -
アウトラインとは l 物事のあらまし・⼤筋・概略 l ドキュメントにおけるアウトラインとは、章・節・項などの⾒出しを 階層的に設定、表⽰したもの l 2つの役割を持つ︓ l 説明の流れをあらかじめ読み⼿に掴ませ、⼼の準備をさせる役割
l 必要とする情報がどこに書かれているか、探しやすくする役割 38 • 概要 • 背景と⽬的 • 調査の⽅法 • データの収集 • データの分析 • 結果と考察 • 結論とまとめ 例︓レポートのアウトライン -
記事の基本構成 l タイトルで、その記事のテーマを伝える l リード⽂で、これから何を述べるのかを伝える l 次に、これから述べることの概要や全体像を伝える l さらに、サブテーマごとの詳細へと展開していく 39
タイトル(≒テーマ) 概要・全体像 ⾒出し(任意) ⾒出し サブテーマ1 ⾒出し サブテーマ2 リード⽂ ü 1つの記事の中でも階層構造をとる ポイント -
伝える情報を分解する 41 スマートフォン 種類 Android iPhone ⽤途 コミュニケーション ウェブブラウジング ・・・
機能 インターネット 写真やビデオの撮影 メディアの再⽣ アプリによる追加機能 通話 センシング 「スマートフォンとは何か」 を伝えてみよう︕ -
分解した要素を並び替える 42 スマートフォン 機能 通話 インターネット 写真やビデオの撮影 メディアの再⽣ センシング アプリによる追加機能
⽤途 コミュニケーション ウェブブラウジング ・・・ 種類 Android iPhone • 重要なことから • 既知から未知へ • 情報のニーズが⼤きいものから • 時系列で のいずれかに並び替える -
⾒出しを付ける要素を選ぶ 43 スマートフォン 機能 通話 インターネット 写真やビデオの撮影 メディアの再⽣ センシング アプリによる追加機能
⽤途 コミュニケーション ウェブブラウジング ・・・ 種類 Android iPhone 内容が少なそうなので、 「概要」に含める 内容が多そうなので、 ⾒出しを付ける -
要素をアウトラインに反映する 44 スマートフォン 機能 通話 インターネット 写真やビデオの撮影 メディアの再⽣ センシング アプリによる追加機能
⽤途 コミュニケーション ウェブブラウジング ・・・ 種類 Android iPhone アウトライン l スマートフォンの概要 l スマートフォンの⽤途 l コミュニケーション l ウェブブラウジング l ・・・ l スマートフォンの種類 l Android l iPhone -
⾒出しを決める 45 スマートフォン 機能 通話 インターネット 写真やビデオの撮影 メディアの再⽣ センシング アプリによる追加機能
⽤途 コミュニケーション ウェブブラウジング ・・・ 種類 Android iPhone ü ⾒出しを⾒るだけで読者が次の情報を読み 取れる⾔葉にする︓ l 説明の流れ l ⾒出しに続く本⽂に何が書かれているか l どのようなときに読む必要があるのか アウトライン l スマートフォンとは l スマートフォンの便利な活⽤⽅法 l 友⼈や家族と会話する l インターネットで情報を得る l ・・・ l スマートフォンの種類 l Androidスマートフォン l iPhone -
トピックを意識する l ⽂章を書き始める前に、段落単位で⽂章 の構成を組む l 1つの段落が1つのトピック(話題)になる l 1つの段落は3⽂〜8⽂程度 l Webでは2⽂〜5⽂程度が⽬安
l 短過ぎると、主張の根拠が不⾜する l ⻑過ぎると、読みづらくなる 47 トピック1 ⾒出し トピック2 トピック3 ⾒出し トピック1 ・・・ -
トピックを意識する効果 l 読み⼿ l 順序⽴てて話題が進むので、頭に⼊りやすい l 段落単位で読み⾶ばしができる l 書き⼿ l
書くべきトピックが決まっていると、書きやすい l 情報の過不⾜が視覚的にわかる 48 -
伝える情報の要素にトピックを割り当てる 49 スマートフォンの機能 通話 インターネット 写真やビデオの撮影 メディアの再⽣ センシング アプリによる追加機能 概要
インターネットのトピック 写真や動画の撮影のトピック センシングのトピック アプリによる機能追加のトピック 段落構成 • 内容が多い要素、重要な要素 にトピックを割り当てる • それ以外は概要に含める -
それぞれのトピックを展開する スマートフォンは、携帯電話とコンピューターの機能を併せ持つ携帯機器です。⼀般的には、タッチスクリーンディスプレイを備 え、通話、インターネット、写真や動画の撮影、⾳楽や動画の再⽣、各種センサーによる周辺情報の取得などの機能を提 供します。また、アプリケーション(アプリ)をインストールして機能を追加することもできます。 スマートフォンは、インターネットへの接続が可能で、モバイルデータネットワークやWi-Fiを使⽤して情報のやり取りができます。 ⽇常⽣活の中で場所を問わず情報にアクセスすることを可能にし、ウェブブラウジング、メディアの視聴、ソーシャルメディアの 利⽤、オンラインショッピング、ビジネス活動など、さまざまな⽬的に使⽤されています。 スマートフォンは、写真や動画の撮影機器としても広く使⽤されています。撮った写真を、スマートフォンを使ってその場で加 ⼯したり、友⼈に共有したり、ソーシャルメディアに投稿したりすることも、撮影の楽しみ⽅の⼀つになっています。 さらに、スマートフォンにはGPSやさまざまなセンサーが組み込まれており、加速度計、ジャイロスコープ、電⼦コンパス、近接
センサー、光センサーなどがあります。これらから得られる周辺情報により、スマートフォンは、地図やナビゲーションを代表例と した、⽇常⽣活を⽀援するさまざまな機能を提供します。 50 トピック 概要 インターネット 写真や動画の撮影 センシング -
トピックの展開 トピックを展開する代表的なパターン︓ l 詳細を述べる 「つまり、〜ということです。」 l 具体例を挙げる 「たとえば、〜があります。」 l 理由を述べる
「その理由は、〜です。」 l データを出す 「次のデータは、〜を⽰しています。」 51 スマートフォンは、インターネットへの接続が可能で、モバイル データネットワークやWi-Fiを使⽤して情報のやり取りができます。 ⽇常⽣活の中で場所を問わず情報にアクセスすることを可能 にし、ウェブブラウジング、メディアの視聴、ソーシャルメディアの 利⽤、オンラインショッピング、ビジネス活動など、さまざまな⽬的 に使⽤されています。 主題 詳細 -
並列の情報は同じ表現で書く 52 Androidスマートフォンは、Google社が開発したAndroidというOSを搭載したスマートフォンです。カスタマイズ性が⾼く、 利⽤者はホーム画⾯にアプリやウィジットなどを⾃由に配置できます。また、Googleのサービスとの統合が強く、Googleマッ プやGoogleカレンダー、Gmailなどのアプリがスマートフォンとシームレスに連携します。多くのメーカーが、さまざまな特⾊を持 つAndroidスマートフォンを幅広い価格帯で販売しているため、利⽤者が⾃分の好みや予算に合わせて選択できることも 魅⼒です。 iPhoneは、Apple社が開発し販売するスマートフォンです。iPhoneはシンプルで洗練されたデザインを特⻑とするiOSと いうOSを搭載し、ハードウェアとの最適化された統合により、⾼いパフォーマンスと優れた利⽤体験を提供します。また、アプ リストアを通してiPhoneに配信されるアプリには厳格な審査基準があり、マルウェアや不正なアプリのリスクを低減するための
セキュリティに重点が置かれています。iOSのアップデートを通じて新機能やセキュリティーの改善が⻑期に渡って頻繁に提供 されることも魅⼒です。 トピック Androidスマートフォン の特徴 iPhoneの特徴 並列の情報は同じ表現で書くと、⽂章の展開を予測してから読めるようになる -
重要なことから書く 55 l Before(理由 → 主張の順) 外出先から空き時間にメールを確認したり、オンラインミーティ ングに参加したり、報告書を提出したりできるようになるので、 業務でスマートフォンを活⽤することが、⽣産性の向上に繋が ります。
l After(主張 → 理由の順) 業務でスマートフォンを活⽤することが、⽣産性の向上に繋が ります。外出先から空き時間にメールを確認したり、オンライン ミーティングに参加したり、報告書を提出したりできるようにな るからです。 ü ドキュメントは、⼀部しか読まれないことを 前提に書く ü 情報に優先度を付けて、優先度が⾼い ことを先に書く ü たとえば、主張(伝えたいこと)は理由よ りも前に書く ポイント -
読者の視点で書く 56 l Before ニュースレターに登録いただくと、アプリのアップデート情報を メールでお送りします。 l After ニュースレターに登録すると、アプリのアップデート情報をメール で受け取れます。
ü 読者の視点で書くことが、読みやすさと、 わかりやすさに繋がる ü 書き⼿やシステムが主語になっていると、 ⾃分視点に置き換えながら読まなくては ならなくなる ポイント -
能動態と受動態を使い分ける 57 l Before スマートフォンをリセットすると、すべてのデータを削除します。 l After スマートフォンをリセットすると、すべてのデータが削除されます。 ü 読者の視点で書くと、読者の操作は能動
態、システムの動作は受動態になる ポイント 読者の操作は能動態で システムの動作は受動態で -
⼀⽂⼀義で書く l Before iPhoneはアップル社が開発し販売するスマートフォンで、シン プルで洗練されたデザインを特⻑とし、⾼い性能を持ち滑らか に動作します。 l After iPhoneはアップル社が開発し販売するスマートフォンです。シ ンプルで洗練されたデザインを特⻑とします。⾼い性能を持ち、
滑らかに動作します。 58 ü 1つの⽂には、1つの事柄だけを書く ü 1⽂に複数の事柄が詰め込まれていると、 内容を整理しながら読まなくてはならなく なる ポイント -
⼀⽂を短くする 59 l Before スマートフォンで写真を撮ることができ、また、撮った写真をその 場で友⼈に共有することもできます。 l After スマートフォンで写真を撮ることができます。また、撮った写真を その場で友⼈に共有することもできます。
l さらに改善 スマートフォンで写真を撮ることができます撮れます。また、 撮った写真をその場で友⼈に共有することもできます。 ü 簡潔、短くを常に意識する ü 「したがって」「また」などの接続詞も、不要 なことが多い ü 「(⽂の)わかりやすさと⻑短とは本質的 には関係がない」(『⽇本語の作⽂技術』 12刷, 本 ⽥勝⼀, P.194)が、書き慣れていない⼈は 「1⽂を短く」を常に意識すべき ポイント -
修飾する側とされる側を近づける 60 l Before スマートフォンは、GPSや電⼦コンパスなどから得られる情報 をもとにして、Googleマップのような専⽤アプリを通じて、ナビ ゲーションの機能を提供します。 l After GPSや電⼦コンパスなどから得られる情報をもとにして、
Googleマップのような専⽤アプリを通じて、スマートフォンは ナビゲーションの機能を提供します。 ü ⽂が⻑くなるときは、修飾する側(主語 や⽬的語)と 修飾される側(述語)を 近づけると、読みやすくなる ポイント -
修飾部が複数あるとき 61 GPSや電⼦コンパスなどから得られる情報をもとにして、 Googleマップのような専⽤アプリを通じて、スマートフォンは ナビゲーションの機能を提供します。 GPSや電⼦コンパスなどから得られる情報をもとにして スマートフォンは ナビゲーションの機能を提供します 修飾する側 修飾される側
ü 修飾部が複数あるときは、⻑い修飾部から 順に書く (『⽇本語の作⽂技術』 , 本⽥勝⼀) ポイント Googleマップのような専⽤アプリを通じて -
読点を適切に打つ 62 l Before スマートフォンには、加速度計やジャイロスコープや近接セン サーや光センサーなどのセンサーが組み込まれています。 l After スマートフォンには、加速度計、ジャイロスコープ、近接セン サーや、光センサーなどのセンサーが組み込まれています。
ü 読みやすさのために、読点は特に重要 ü 読点を適切に打つことで、係り受けや並列 関係がはっきりし、⽂章が読みやすくなる ポイント -
読点のパターン 63 例 説明 メーカーにより、提供されるアップデートの頻度は異なります。 係り受けを明確にするために打つ スマートフォンには、加速度計、ジャイロスコープや、近接セン サーなどのセンサーが組み込まれています。 並列関係を明確にするために打つ 最新のアップデートを適⽤することで、悪意のある攻撃やデータ
漏洩などのリスクを減らすことができます。 理由・条件・⽬的などを明確にするために打つ スマートフォンは、社会的なつながりや情報へのアクセスを容易 にし、⽇常⽣活のさまざまな場⾯で利⽤されています。 節の区切りを明確にするために打つ しかし、近年ではスマホ中毒と呼ばれる依存症の問題が指摘さ れています。 接続詞の後ろに打つ(接続関係を強調した い場合) -
並列の情報には箇条書きを使う 64 l Before スマートフォンには、加速度計、ジャイロスコープ、近接セン サーや、光センサーなどのセンサーが組み込まれています。 l After スマートフォンには、次のようなセンサーが組み込まれています。 l
加速度計 l ジャイロスコープ l 近接センサー l 光センサー ü 並列の情報を並べるときは、箇条書きを 活⽤すると、並列関係が視覚的にわかり やすくなる ポイント -
できるだけ具体的に書く 65 l Before 例1︓ スマートフォンの⾳量の設定を確認してください。 例2︓ iPhoneは簡単に使えます。 l After
例1︓ スマートフォンが消⾳の設定になっていないことを確認 してください。 例2︓ iPhoneは、アイコンベースのホーム画⾯やタッチによる 操作など、使い⽅が直感的に理解できるように設計 されています。 ü 曖昧な表現は、書き⼿の意図通りに伝 わらない ü 具体的に書く努⼒を ポイント -
肯定形で書く 66 l Before ソフトウェアのアップデートは放置したままにしないでください。 l After ソフトウェアのアップデートはなるべく早めに適⽤してください。 ü 否定表現は意味を曖昧にする
ü 肯定形で表現できる場合は、なるべく肯定 形を使う ü 禁⽌事項を伝える場合は、敢えて否定形 で書くのも良い 例︓電源を切らないでください ポイント -
肯定形で書くと、印象も変わる 67 l Before 5名以上の予約は受け付けられません。 l After 4名まで予約できます。 ü 否定表現は、理解に時間がかかるだけで
なく、ネガティブな印象を招く ü 肯定形に書き換えることで、簡潔でポジ ティブな印象になる ポイント -
⼆重否定を使わない 68 l Before 信頼できないアプリはインストールしないでください。 l After 信頼できるアプリだけをインストールしてください。 ü 否定表現は、1つの⽂に1つまで
ü ⼆重否定は⽂章をわかりづらくし、読者 の混乱を招く ポイント -
チェックシート ü 冒頭に概要を書いていますか︖ ü ⼀⽂⼀義で書いていますか︖ ü 読者の視点で書いていますか︖ ü 重要なことから書いていますか︖ ü
⽂はこれ以上短くなりませんか︖ ü 曖昧な表現はありませんか︖ ü 係り受けは明確ですか︖ ü 否定⽂は肯定形で書けませんか︖ ü 修飾する側とされる側が離れ過ぎていませんか︖ 69