テクニカルライティングの基本を学べます。サイボウズの新入社員向け研修資料です。業務マニュアル、報告書、仕様書、技術解説書などのドキュメントを書く機会がある方向け。 https://twitter.com/naoh_nak
テクニカルライティングの基本2022年5月17日 開運研修2022開発本部 テクニカルコミュニケーションチーム 仲田1
View Slide
2仲田 尚央Nakata Naohiro@naoh_nak開発本部 テクニカルコミュニケーションチームテクニカルライター/ローカライズ 職能マネージャーお仕事の内容：⚫ サイボウズ製品のUIテキストを書く⚫ 製品のマニュアルやヘルプを書く⚫ それらを他の言語に展開する（ローカライズ）
テクニカルライティングは3読者や目的に合わせて技術をわかりやすく伝える手法です。
みなさんは、これから「ドキュメント」を書く機会が多くあります。4
⚫ 報告書や企画書を書く⚫ 業務マニュアルを書く⚫ 製品や機能の解説を書く⚫ 作業手順書を書く⚫ 製品の仕様書を書く⚫ …5
ドキュメントは多くの人に読まれます6業務マニュアル
書き手の工夫で、多くの人の時間を節約できます7業務マニュアル
書き方の方法論を学ぶことで、書き手の時間も節約できます8業務マニュアル
チームワークのために、情報共有は欠かせません。良いドキュメントを書くことは、効率的な情報共有に繋がります。9
テクニカルライティングの適用対象⚫ いわゆる「実用文」が求められるもの⚫ 議事録⚫ 報告書⚫ 技術書・解説書⚫ 仕様書⚫ マニュアル・FAQなどなど10
ドキュメントの前提1 - 求める情報が人によって違う11業務マニュアル作業Aの手順を知りたい。入社したばかりで何もわからん。今度担当することになった業務Bについて、一通り全部学びたい。インストールが必要なツールを知りたい。・・・
ドキュメントの前提2 - 情報の探し方も違う12業務マニュアル作業Aの手順を知りたい。入社したばかりで何もわからん。今度担当することになった業務Bについて、一通り全部知っておきたい。インストールが必要なツールを知りたい。・・・知りたいことが明確知りたいことが曖昧網羅的に知りたい
ドキュメントの前提3 – 一意に伝わる必要がある13✕✕✕
ドキュメントの前提4 – 一部しか読まれない14
テクニカルライティングの要素15Effectiveness必要な情報を正しく得られるSatisfaction不快さがなく、肯定的に受け止められるEfficiency効率よく理解できるユーザビリティーの定義（ISO 9241-11）から
それぞれの要素に対して取る手段16Effectiveness必要な情報を正しく得られるSatisfaction不快さがなく、肯定的に受け止められるEfficiency効率よく理解できる• 曖昧さを排し、明確に書く• できるだけ具体的に書く• 誤解なく読める文章で書く• 情報を適切に整理、構造化する• どこに何が書いてあるかをわかりやすくする• 簡潔で読みやすい文章で書く• 必要な情報だけを書く• 肯定的な表現で書く• ですます調で書く（過剰な敬語にはしない）
テクニカルライティングの進め方1. 伝える情報を整理する2. アウトラインを作る3. わかりやすく、簡潔な文章で書く17
伝える情報を整理する18
整理の鉄則19概要から具体へまたは全体から部分へ
20伝えるテーマテーマ1テーマ1-1テーマ1-1-1テーマ1-1-2テーマ1-2テーマ2テーマ2-1テーマ2-2概要全体具体部分具体例で分解構成要素で分解
書籍や文書の場合21伝えるテーマテーマ1テーマ1-1テーマ1-1-1テーマ1-1-2テーマ1-2テーマ2テーマ2-1テーマ2-2章 節 項
Webの場合22伝えるテーマテーマ1テーマ1-1テーマ1-1-1テーマ1-1-2テーマ1-2テーマ2テーマ2-1テーマ2-2カテゴリー ページ 見出し
全体から部分へと分解する23kintoneアプリレコードフィールドコメントビュー（一覧）アクセス権・・・スペース公開スペース非公開スペースゲストスペースピープルメッセージ
概要から具体へと分解する24スマートフォンAndroidPixelXperiaGalaxy・・・iOSiPhone Pro MaxiPhone ProiPhone mini・・・
順に説明を展開していく25スマートフォンAndroidPixelXperiaGalaxy・・・iOSiPhone Pro MaxiPhone ProiPhone mini・・・段階を追って知識を付け加えていくことが、わかりやすさに繋がる
情報を適切に分解すると、読者が情報を探しやすくなる26スマートフォンAndroidPixelXperiaGalaxy・・・iOSiPhone Pro MaxiPhone ProiPhone mini・・・前知識がない人は、最初から読み、興味を持った項目へと進む特定の知識が欲しい人は、その項だけを読むさわりだけを知りたい人は、概要だけを読むどこに何が書いてあるかがわかるよう、適切なタイトルと見出しを付けよう
分解には複数のやり方がある27スマートフォンコミュニケーション・・・・・・ニュース・・・・・・買い物ナビゲーム・・・
情報整理の例 - 良いヘルプの要素を分解する⚫ まず、良いヘルプの要素を具体化する⚫ 要素ごとに、どうすれば満たせるかを考察していく28良いヘルプ役に立つターゲットユーザーの設定情報の収集方法探しやすい情報の分類タイトルや見出しの付け方検索最適化わかりやすい用語の統一読みやすい文章の書き方図解正しい ・・・
情報整理の例 - 説明の構成に反映する29誰に何を伝えるかを整理する『ヘルプサイトの作り方』 章構成良いヘルプ役に立つターゲットユーザーの設定情報の収集方法探しやすい情報の分類タイトルや見出しの付け方検索最適化わかりやすい用語の統一読みやすい文章の書き方図解正しい ・・・ユーザーの使い方を意識して構成を設計するユーザーの動線からナビゲーションを設計するスタイルガイドと用語集を準備する記事を書く - 文章と図解のテクニック・・・
アウトラインを作る30
記事で伝える情報を書き出すテーマ：kintoneでアプリを開発する方法を解説する伝えることを書き出した例：⚫ アプリ開発を開始する前に必要な準備⚫ 開発中のアプリを保存し、中断する方法⚫ 保存したアプリを開いて、アプリ開発を再開する方法⚫ 簡単なアプリを例にしたアプリ開発手順⚫ アプリのアイコンの作り方⚫ 開発したアプリに機能を追加する方法⚫ エラーへの対処方法31✓ この段階では、順番や言葉の表現などの細かいことは気にしない✓ 情報を漏れなく洗い出すことを重視ポイント
書き出した情報を整理する伝える情報を整理した例：⚫ アプリ開発の全体の流れ⚫ 簡単なアプリを例にしたアプリ開発手順⚫ アプリ開発を開始する前の準備⚫ 開発手順⚫ アプリのアイコンの作り方⚫ 開発中のアプリを保存し、中断する方法⚫ 保存したアプリを開き、アプリ開発を再開する方法⚫ エラーへの対処方法⚫ 開発したアプリに機能を追加する方法32✓ まず概要を述べる✓ 読者がどのように情報を探そうとするかを意識して、情報を整理する✓ どのタイミングで必要になる情報かを意識して、項目を並び替えるポイント
見出しを決める見出し構造の例：⚫ アプリ開発の流れ⚫ アプリを開発しよう⚫ 開発を始める前に⚫ ○○○を設定しよう⚫ ○○○を設定しよう⚫ ○○○を設定しよう⚫ アプリのアイコンを作ろう⚫ アプリ開発を中断する場合⚫ アプリ開発を再開するには⚫ アプリ開発中にエラーになったら⚫ アプリに機能を追加しよう33✓ 読者が次の情報を読み取れる言葉にすることを意識する：⚫ 見出しに続く本文に何が書かれているか⚫ どのようなときに読む必要があるのかポイント
わかりやすく、簡潔な文章で書く34
書くときの心構え⚫ 読者の行動をイメージしながら書くどんな人が、どんな情報を、どのように探すか⚫ （自分ではなく）読者の視点で書く⚫ 簡潔に、できるだけ短文で書く⚫ 重要なことから書く35
重要なことから書く36⚫ Beforeシステムを正常に起動できなくなる恐れがあるので、アップデート中は電源を切らないでください。⚫ Afterアップデート中は電源を切らないでください。システムを正常に起動できなくなります。✓ ドキュメントは、一部しか読まれないことを前提に書く✓ 情報に優先度を付けて、優先度が高いことを先に書くポイント
一文一義で書く⚫ Beforeサイボウズ Officeは、クラウド型グループウェアで、情報を共有する各種機能、メッセージ機能やワークフロー機能などを備え、使いやすさが特長です。⚫ Afterサイボウズ Officeは、クラウド型グループウェアです。情報を共有する各種機能、メッセージ機能やワークフロー機能などを備えています。使いやすさがサイボウズOfficeの特長です。37✓ 1つの文には、1つの事柄だけを書く✓ 1文に複数の事柄が詰め込まれていると、内容を整理しながら読まなくてはならなくなるポイント
簡潔に書く38⚫ Beforeほかのユーザーの連絡先を確認でき、また、ほかのユーザーにメッセージを送ることもできます。⚫ Afterほかのユーザーの連絡先を確認できます。また、ほかのユーザーにメッセージを送ることもできます。⚫ さらに改善ほかのユーザーの連絡先を確認できます。また、ほかのユーザーにメッセージを送ることもできます。✓ 簡潔、短くを常に意識する✓ 「したがって」「または」などの接続詞も、不要なことが多いポイント
読者の視点で書く39⚫ Beforeニュースレターに登録いただくと、製品のアップデート情報をメールでお送りします。⚫ Afterニュースレターに登録すると、製品のアップデート情報をメールで受け取れます。✓ 読者の視点で書くことが、読みやすさと、わかりやすさに繋がる✓ システムが主語になっていると、自分視点に置き換えながら読まなくてはならなくなるポイント
能動態と受動態を使い分ける40⚫ Before[削除]をクリックすると、すべてのデータを削除します。⚫ After[削除]をクリックすると、すべてのデータが削除されます。✓ 読者の視点で書くと、読者の操作は能動態、システムの動作は受動態になるポイント能動態 受動態
できるだけ具体的に書く41⚫ Beforeメール通知の設定を確認してください。間隔を少しだけ空ける必要があります。⚫ Afterメール通知が有効になっていることを確認してください。3～5mmの間隔が必要です。✓ 曖昧な表現は、書き手の意図通りに伝わらない✓ 具体的に書く努力をポイント
肯定形で書く42⚫ Before5名以上の予約は受け付けられません。⚫ After4名まで予約できます。✓ 否定表現は、理解に時間がかかるだけでなく、ネガティブな印象を招く✓ 肯定形に書き換えることで、簡潔でポジティブな印象になるポイント
二重否定を使わない43⚫ BeforeファイルA以外は削除しないでください。⚫ AfterファイルAだけを削除してください。✓ 否定表現は、1つの文に1つまで✓ 二重否定は文章をわかりづらくし、読者の混乱を招くポイント
係り受けを明確にする44⚫ Before消毒液Aのように刺激の強くない消毒液を使ってください。⚫ After消毒液Aのような、刺激の強くない消毒液を使ってください。または消毒液Aのように刺激の弱い消毒液を使ってください。✓ 係り受けが不明確な文章は、まったく逆の意味に受け取られることがあるポイント消毒液Aは使って良いの？
主語や目的語と、述語を近づける45⚫ Beforeデータは、自動同期を無効にした場合は手動で同期しない限りバックアップされません。⚫ After自動同期を無効にした場合は、手動で同期しない限りデータはバックアップされません。✓ 文が長くなるときは、主語や目的語と述語を近づけると読みやすくなるポイント
列記には箇条書きを使う46⚫ Before名前、住所、メールアドレス、電話番号、および誕生日の入力は任意です。⚫ After次の項目の入力は任意です。⚫ 名前⚫ 住所⚫ メールアドレス⚫ 電話番号⚫ 誕生日✓ 項目を並べるときは箇条書きを活用すると、並列関係が視覚的にわかりやすくなるポイント
おまけ47
ショートケーキを説明する48ショートケーキは、イチゴとホイップクリームをふんだんに使った、シンプルなのに華やかなケーキだ。イチゴ好きにも、クリーム好きにもたまらない。刻んだイチゴを混ぜたホイップクリームをつなぎにして、柔らかなスポンジを何層か重ねる。さらに、その周りをホイップクリームで包み込み、イチゴを載せて飾り付ける。イチゴとホイップクリームは、お互いを引き立て合う存在だ。真っ白なホイップクリームは、イチゴの赤色をより鮮やかに映えさせる。そして甘酸っぱいイチゴは、ホイップクリームの甘さをより強く感じさせてくれる。その絶妙な組み合わせは、目にも舌にも素晴らしい。まず全体を言う魅力も沿えると、なお良いショートケーキの構成要素へと進む要素同士の関係を語る
チェックシート✓ 冒頭に概要を書いていますか？✓ 一文一義で書いていますか？✓ 読者の視点で書かれていますか？✓ 重要なことから書かれていますか？✓ 文はこれ以上短くなりませんか？✓ 曖昧な表現はありませんか？✓ 係り受けは明確ですか？✓ 二重否定になっていませんか？✓ 主語や目的語と動詞の位置が離れすぎていませんか？49
naohiro_nakata
khelene815
hacobu
socialmatch
maasa_0113
nyattx
recruitengineers
harmonia_inc
shippio
conocerhr
inetoagave
o2mami
philhawksworth
3n
jeffersonlam
jennybc
bkeepers
sstephenson
lynnandtonic
rocio
sachag
brad_frost
aki_iinuma
addyosmani