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

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

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

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

本資料をもとにした書籍も発売中です:https://amzn.asia/d/2hQNEk2
Twitter:https://twitter.com/naoh_nak
2023年度のアップデート版もあります:https://speakerdeck.com/naohiro_nakata/technicalwriting2023

Naohiro Nakata

June 01, 2022
Tweet

More Decks by Naohiro Nakata

Other Decks in Business

Transcript

  1. 2 仲田 尚央 Nakata Naohiro @naoh_nak 開発本部 テクニカルコミュニケーションチーム テクニカルライター/ローカライズ 職能マネージャー

    お仕事の内容: ⚫ サイボウズ製品のUIテキストを書く ⚫ 製品のマニュアルやヘルプを書く ⚫ それらを他の言語に展開する(ローカライズ)
  2. それぞれの要素に対して取る手段 16 Effectiveness 必要な情報を正しく得られる Satisfaction 不快さがなく、肯定的に 受け止められる Efficiency 効率よく理解できる •

    曖昧さを排し、明確に書く • できるだけ具体的に書く • 誤解なく読める文章で書く • 情報を適切に整理、構造化する • どこに何が書いてあるかをわかりやすくする • 簡潔で読みやすい文章で書く • 必要な情報だけを書く • 肯定的な表現で書く • ですます調で書く (過剰な敬語にはしない)
  3. 全体から部分へと分解する 23 kintone アプリ レコード フィールド コメント ビュー(一覧) アクセス権 ・・・

    スペース 公開スペース 非公開スペース ゲストスペース ピープル メッセージ
  4. 順に説明を展開していく 25 スマートフォン Android Pixel Xperia Galaxy ・・・ iOS iPhone

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

    Pro Max iPhone Pro iPhone mini ・・・ 前知識がない人は、最初 から読み、興味を持った 項目へと進む 特定の知識が欲しい人は、 その項だけを読む さわりだけを知りたい人は、 概要だけを読む どこに何が書いてあるかがわかるよう、適切なタイトルと見出しを付けよう
  6. 情報整理の例 - 良いヘルプの要素を分解する ⚫ まず、良いヘルプの要素を具体化する ⚫ 要素ごとに、どうすれば満たせるかを考察し ていく 28 良いヘルプ

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

    情報の収集方法 探しやすい 情報の分類 タイトルや見出しの付け方 検索最適化 わかりやすい 用語の統一 読みやすい文章の書き方 図解 正しい ・・・ ユーザーの使い方を意識して構成を設計する ユーザーの動線からナビゲーションを設計する スタイルガイドと用語集を準備する 記事を書く - 文章と図解のテクニック ・・・
  8. 記事で伝える情報を書き出す テーマ: kintoneでアプリを開発する方法を解説する 伝えることを書き出した例: ⚫ アプリ開発を開始する前に必要な準備 ⚫ 開発中のアプリを保存し、中断する方法 ⚫ 保存したアプリを開いて、アプリ開発を再開する方法

    ⚫ 簡単なアプリを例にしたアプリ開発手順 ⚫ アプリのアイコンの作り方 ⚫ 開発したアプリに機能を追加する方法 ⚫ エラーへの対処方法 31 ✓ この段階では、順番や言葉の表現などの 細かいことは気にしない ✓ 情報を漏れなく洗い出すことを重視 ポイント
  9. 書き出した情報を整理する 伝える情報を整理した例: ⚫ アプリ開発の全体の流れ ⚫ 簡単なアプリを例にしたアプリ開発手順 ⚫ アプリ開発を開始する前の準備 ⚫ 開発手順

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

    ⚫ ◦◦◦を設定しよう ⚫ ◦◦◦を設定しよう ⚫ アプリのアイコンを作ろう ⚫ アプリ開発を中断する場合 ⚫ アプリ開発を再開するには ⚫ アプリ開発中にエラーになったら ⚫ アプリに機能を追加しよう 33 ✓ 読者が次の情報を読み取れる言葉にすること を意識する: ⚫ 見出しに続く本文に何が書かれているか ⚫ どのようなときに読む必要があるのか ポイント
  11. 一文一義で書く ⚫ Before サイボウズ Officeは、クラウド型グループウェアで、情報 を共有する各種機能、メッセージ機能やワークフロー機 能などを備え、使いやすさが特長です。 ⚫ After サイボウズ

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

    ⚫ さらに改善 ほかのユーザーの連絡先を確認できます。また、ほかのユー ザーにメッセージを送ることもできます。 ✓ 簡潔、短くを常に意識する ✓ 「したがって」「または」などの接続詞も、不 要なことが多い ポイント
  13. 読者の視点で書く 39 ⚫ Before ニュースレターに登録いただくと、製品のアップデート情報 をメールでお送りします。 ⚫ After ニュースレターに登録すると、製品のアップデート情報を メールで受け取れます。

    ✓ 読者の視点で書くことが、読みやすさと、 わかりやすさに繋がる ✓ システムが主語になっていると、自分視点 に置き換えながら読まなくてはならなくなる ポイント
  14. 肯定形で書く 42 ⚫ Before 5名以上の予約は受け付けられません。 ⚫ After 4名まで予約できます。 ✓ 否定表現は、理解に時間がかかるだけで

    なく、ネガティブな印象を招く ✓ 肯定形に書き換えることで、簡潔でポジ ティブな印象になる ポイント
  15. 係り受けを明確にする 44 ⚫ Before 消毒液Aのように刺激の強くない消毒液を使ってください。 ⚫ After 消毒液Aのような、刺激の強くない消毒液を使ってくださ い。 または

    消毒液Aのように刺激の弱い消毒液を使ってください。 ✓ 係り受けが不明確な文章は、まったく逆 の意味に受け取られることがある ポイント 消毒液Aは使って良いの?
  16. 列記には箇条書きを使う 46 ⚫ Before 名前、住所、メールアドレス、電話番号、および誕生日の入力は任 意です。 ⚫ After 次の項目の入力は任意です。 ⚫

    名前 ⚫ 住所 ⚫ メールアドレス ⚫ 電話番号 ⚫ 誕生日 ✓ 項目を並べるときは箇条書きを活用する と、並列関係が視覚的にわかりやすくなる ポイント
  17. チェックシート ✓ 冒頭に概要を書いていますか? ✓ 一文一義で書いていますか? ✓ 読者の視点で書かれていますか? ✓ 重要なことから書かれていますか? ✓

    文はこれ以上短くなりませんか? ✓ 曖昧な表現はありませんか? ✓ 係り受けは明確ですか? ✓ 二重否定になっていませんか? ✓ 主語や目的語と動詞の位置が離れすぎていませんか? 49