技術をわかりやすく伝えるためのテクニックとしての「テクニカルライティング」を学べます。Developers Summit 2023の登壇資料。開発者・エンジニアの方向け。 https://twitter.com/naoh_nak
技術をわかりやすく伝えるためのテクニカルライティングDevelopers Summit 20232月10日 17:45-仲田 尚央@cybozu1
View Slide
2仲田 尚央Nakata Naohiro@naoh_nakサイボウズテクニカルライターとローカライズの職能マネージャーお仕事の内容：⚫ サイボウズ製品のUIテキストを書く⚫ 製品のマニュアルやヘルプを書く⚫ それらを他の言語に展開する（ローカライズ）複業としてライティング講習もしています5歳と2歳の子供がいます
はじめに、おことわり⚫ 本セッションは、サイボウズのエンジニア向け研修を編集したものです⚫ 公開資料と内容が一部重複します3https://blog.speakerdeck.com/2022-most-viewed-decks/
技術を伝えるということ⚫ エンジニアには、知識や学びを共有しあう素晴らしい文化があります⚫ しかし、いかに深い技術も、整理されないままでは読者に伝わりません⚫ うまく整理されていても、それが適切に文章構成に反映されていなくては、情報の価値は下がってしまいます4
本講の流れ1. テクニカルライティングの基本的な考え方を知る2. 情報を適切に整理するためのコツを知る3. 文章の構成を組むためのコツを知る4. わかりやすい文章を書くためのコツを知る5✓ 本講では、文章の書き方だけでなく、情報をどう整理するかにも重点を置いています。
エンジニアは「ドキュメント」を書く機会が多くあります。6
⚫ 仕様書を書く⚫ 作業手順書を書く⚫ 技術ブログを書く⚫ 業務マニュアルを書く⚫ リリースノートを書く⚫ …7
ドキュメントの前提1 - 求める情報が人によって違う8業務マニュアル作業Aの手順を知りたい。入社したばかりで何もわからん。今度担当することになった業務Bについて、一通り全部知っておきたい。インストールが必要なツールを知りたい。・・・
ドキュメントの前提2 - 情報の探し方も違う9業務マニュアル作業Aの手順を知りたい。入社したばかりで何もわからん。今度担当することになった業務Bについて、一通り全部知っておきたい。インストールが必要なツールを知りたい。・・・知りたいことが明確知りたいことが曖昧網羅的に知りたい
ドキュメントの前提3 – 一意に伝わる必要がある10✕✕✕
ドキュメントの前提4 – 一部しか読まれない11
テクニカルライティングの要素12Effectiveness必要な情報を正しく得られるSatisfaction不快さがなく、肯定的に受け止められるEfficiency効率よく理解できるユーザビリティーの定義（ISO 9241-11）から
それぞれの要素に対して取る手段13Effectiveness必要な情報を正しく得られるSatisfaction不快さがなく、肯定的に受け止められるEfficiency効率よく理解できる• 曖昧さを排し、明確に書く• できるだけ具体的に書く• 誤解なく読める文章で書く• 情報を適切に整理、構造化する• どこに何が書いてあるかをわかりやすくする• 簡潔で読みやすい文章で書く• 必要な情報だけを書く• 肯定的な表現で書く• ですます調で書く（過剰な敬語にはしない）
それぞれの要素に対して取る手段14Effectiveness必要な情報を正しく得られるSatisfaction不快さがなく、肯定的に受け止められるEfficiency効率よく理解できる• 曖昧さを排し、明確に書く• できるだけ具体的に書く• 誤解なく読める文章で書く• 情報を適切に整理、構造化する• どこに何が書いてあるかをわかりやすくする• 簡潔で読みやすい文章で書く• 必要な情報だけを書く• 肯定的な表現で書く• ですます調で書く（過剰な敬語にはしない）“ユーザビリティーの高いドキュメント”を書けるようになる
テクニカルライティングの進め方15テーマ見出し段落文章①伝える情報を整理する②見出し単位でアウトラインを作る③段落単位で文章の骨組みを作る④わかりやすく、簡潔な文章で書く
Step①：伝える情報を整理する16
ドキュメントの階層ドキュメントは階層構造が基本⚫ 1つのドキュメントで、1つのテーマを⚫ 1つの見出しで、1つのサブテーマを⚫ 1つの段落で、1つのトピックを17メインテーマ見出し段落＝トピック段落＝トピック段落＝トピック見出し段落＝トピック段落＝トピック段落＝トピックサブテーマサブテーマ伝える情報を階層構造に整理する
整理の鉄則18概要から具体へまたは全体から部分へ
19伝えるテーマテーマ1テーマ1-1テーマ1-1-1テーマ1-1-2テーマ1-2テーマ2テーマ2-1テーマ2-2概要全体具体部分具体例で分解構成要素で分解
書籍や文書の場合20伝えるテーマテーマ1テーマ1-1テーマ1-1-1テーマ1-1-2テーマ1-2テーマ2テーマ2-1テーマ2-2章 節 項
Webの場合21伝えるテーマテーマ1テーマ1-1テーマ1-1-1テーマ1-1-2テーマ1-2テーマ2テーマ2-1テーマ2-2カテゴリー ページ 見出し
全体から部分へと分解する22CI/CDCI/CDとは継続的インテグレーションビルド統合テスト継続的デリバリー継続的デプロイCI/CDの実践バージョン管理システムCI/CDパイプライン実行環境
概要から具体へと分解する23スマートフォンAndroidPixelXperiaGalaxy・・・iOSiPhone Pro MaxiPhone ProiPhone mini・・・
順に説明を展開していく24スマートフォンAndroidPixelXperiaGalaxy・・・iOSiPhone Pro MaxiPhone ProiPhone mini・・・段階を追って知識を付け加えていくことが、わかりやすさに繋がる
情報を適切に分解すると、読者が情報を探しやすくなる25スマートフォンAndroidPixelXperiaGalaxy・・・iOSiPhone Pro MaxiPhone ProiPhone mini・・・前知識がない人は、最初から読み、興味を持った項目へと進む特定の知識が欲しい人は、その項だけを読むさわりだけを知りたい人は、概要だけを読むどこに何が書いてあるかがわかるよう、適切なタイトルと見出しを付けよう
分解には複数のやり方がある26スマートフォンコミュニケーション・・・・・・ニュース・・・・・・買い物ナビゲーム・・・
情報の適切な分解って？27NG：きれいに分解できるOK：読者の目的に合わせる
28スマートフォンを買うAndroidPixelXperiaGalaxy・・・iOSiPhone Pro MaxiPhone ProiPhone mini・・・初めてのスマートフォンどれを選べばいいの？種類が多すぎて…スマートフォンをOSや機種の具体例で分解
スマートフォンを使いこなすコミュニケーション・・・・・・ニュース・・・・・・買い物ナビゲーム・・・29スマートフォン買ったよ！使いこなしたいスマートフォンを用途の具体例で分解
スマートフォンスマートフォンを買うAndroidiOSスマートフォンを使いこなすコミュニケーションニュース買い物ナビゲーム30分解方法は、サブテーマごとに異なってもいいただし、同じ枝の同階層での混在はダメOSや機種の具体例で分解用途の具体例で分解
Step②：アウトラインを作る33
アウトラインとは⚫ アウトラインとは：物事のあらまし。大筋。概略。⚫ ドキュメントにおけるアウトラインとは、章・節・項などの見出しを階層的に設定、表示したもの⚫ 2つの役割を持つ：⚫ あらかじめ説明の流れを読み手に掴ませ、心の準備をさせる役割⚫ 必要とする情報がどこに書かれているか、探しやすくする役割34
読み手の予想通りに文章を展開する⚫ 読み手の予想通りに文章を展開することで、読み手は一読で文章を理解できるようになる⚫ そのために、先に概要や全体像を伝えたあとで、そこで述べた順番のままに、詳しい説明を展開していく35CI/CDとは、 です。CI/CDには、継続的インテグレーション、継続的デプロイ、継続的デリバリーの3つの要素があります。継続的インテグレーションとは継続的デプロイとは継続的デリバリーとは
記事の基本構成⚫ タイトルで、そのページのテーマを伝える⚫ リード文で、これから何を述べるのかを伝える⚫ 次に、概要や全体像を伝える⚫ さらに、サブテーマごとの詳細へと展開していく36タイトル（≒テーマ）概要・全体像見出し（任意）見出しサブテーマ1見出しサブテーマ2リード文✓ 1つの記事の中でも階層構造をとるポイント
アウトラインを作る流れ1. 記事で伝える情報を書き出す2. 書き出した情報を整理する3. 見出しを決める37
38CI/CDCI/CDとは継続的インテグレーションビルド統合テスト継続的デリバリー継続的デプロイCI/CDの実践バージョン管理システムCI/CDパイプライン実行環境ココを1記事として書いてみよう
記事で伝える情報を書き出すテーマ： CI/CDとは伝えることを書き出した例：⚫ CI/CDの概要⚫ なぜCI/CDが必要なのか⚫ CI/CDのメリット⚫ アジャイル開発との関係⚫ CI/CDツールの紹介⚫ CI/CDパイプラインの流れ⚫ 継続的インテグレーションとは⚫ 継続的デリバリーとは⚫ 継続的デプロイとは39✓ テーマを分解してできた要素に加えて、記事で伝えるべきことを書き出す✓ この段階では、順番や言葉の表現などの細かいことは気にしない✓ 粒度もバラバラでOK✓ 情報を漏れなく洗い出すことを重視するポイントテーマを分解してできた要素
書き出した情報を整理する伝える情報を整理した例：⚫ CI/CDの概要⚫ なぜCI/CDが必要なのか⚫ アジャイル開発との関係⚫ CI/CDのメリット⚫ CI/CDのプロセス⚫ 継続的インテグレーション⚫ 継続的デリバリー⚫ 継続的デプロイ⚫ CI/CDパイプラインの流れ⚫ CI/CDツールの紹介40✓ 書き出した情報を階層化する✓ 同じ階層は同じ粒度になるように✓ 順番も意識する⚫ 重要度で並べる⚫ 時系列で並べる⚫ 既知から未知へと並べるポイント
見出しを決める見出し構造（＝アウトライン）の例：⚫ CI/CDとは⚫ CI/CDが必要になる背景⚫ アジャイル開発との関係 → 段落に⚫ CI/CDのメリット → 段落に⚫ CI/CDの3つのプロセス⚫ 継続的インテグレーション⚫ 継続的デリバリー⚫ 継続的デプロイ⚫ CI/CDパイプラインの流れ → 段落に⚫ CI/CDに必要なツール41✓ 見出しを見るだけで読者が次の情報を読み取れる言葉にする：⚫ 説明の流れ⚫ 見出しに続く本文に何が書かれているか⚫ どのようなときに読む必要があるのか✓ 書く内容が少なければ、見出しを外し、段落へと格下げするポイント
Step③：段落単位で文章の骨組みを作る42
トピックを意識する⚫ 文章を書き始める前に、段落単位で文章の構成を組む⚫ 1つの段落が1つのトピック（話題）になる⚫ 1つの段落は3文～8文程度⚫ Webでは2文～5文程度が目安⚫ 短過ぎると、主張の根拠が不足する⚫ 長過ぎると、読みづらくなる43トピック1見出しトピック2トピック3見出しトピック1・・・
トピックを意識する効果⚫ 読み手⚫ 順序立てて話題が進むので、頭に入りやすい⚫ 段落単位で読み飛ばしができる⚫ 書き手⚫ 書くべきトピックが決まっていると、書きやすい⚫ 情報の過不足が視覚的にわかる44
テーマ > トピック > 文章 の流れ1. テーマをトピックに分解する2. トピックごとの関係を考える3. 各トピックの詳細（文章）を書く45
テーマをトピックに分解する46⚫ テーマCI/CDのプロセス⚫ トピック⚫ 継続的インテグレーションについて⚫ 継続的デリバリーについて⚫ 継続的デプロイについて⚫ テーマCI/CDが必要になる背景⚫ トピック⚫ 現代のソフトウェア開発では、複数の開発者による並行開発が必要になること⚫ 複数の開発者がソフトウェアに同時に変更を加えると、変更が競合する可能性があること⚫ CI/CDは、そのようなリスクを低減すること
⚫ テーマCI/CDが必要になる背景⚫ トピック⚫ 現代のソフトウェア開発では、複数の開発者による並行開発が必要になること⚫ 複数の開発者がソフトウェアに同時に変更を加えると、変更が競合する可能性があること⚫ CI/CDは、そのようなリスクを低減することトピックごとの関係を考える47並列のトピック 順列のトピック⚫ テーマCI/CDのプロセス⚫ トピック⚫ 継続的インテグレーションについて⚫ 継続的デリバリーについて⚫ 継続的デプロイについて
並列のトピックを詳細へと展開する継続的インテグレーションは、変更があったコードを自動的にビルド・統合・テストし、ソフトウェアの品質を安定的に保つ開発プロセスです。ビルドからテストまでのサイクルを継続的に実行することで、開発中に発生するバグを迅速に改修します。継続的デリバリーは、継続的インテグレーションに続くプロセスとして、テストされたソフトウェアをテスト環境に自動的にデプロイするプロセスのことを言います。実際に触って使えるソフトウェアを継続的に提供することで、ソフトウェアの更新を、お客様に提供する前に検証できます。継続的デプロイは、テストされたソフトウェアを本番環境にまで自動的にデプロイするプロセスです。開発者による最新の変更を顧客が使用できるようにします。継続的デリバリーと継続的デプロイの違いは、本番環境への適用に手動での承認を必要とするか否かという点です。48並列の情報は同じ表現で書くトピック①トピック②トピック③
順列のトピックを詳細へと展開する49順列の情報は既知から未知へと順を追って理解できるように書く現代のソフトウェア開発では、複数の開発者が複数の機能を並行開発していくことが一般的になっています。ソフトウェアが大規模化し、求められる開発スピードも増しているからです。複数の開発者がコードを追加したりライブラリーを追加したりすると、それらの変更が競合したり、依存関係が発生したりすることがあります。開発者のローカルでの開発が長く続けば続くほど、コードをマージしたときに競合や不具合が発生するリスクが高まります。このようなリスクを低減するため、CI/CDと呼ばれる開発プロセスでは、開発者は共有リポジトリーに継続的にコミットします。コミットのたびにビルドとテストを自動的に実行することで、コードの品質を安定的に保ちます。多くの場合、1日に複数回もの高頻度でビルドとテストのサイクルを回します。トピック①トピック②トピック③
トピックの展開トピックを展開していく代表的なパターン：⚫ 詳細を述べる「つまり、～ということです。」⚫ 具体例を挙げる「たとえば、～があります。」⚫ 理由を述べる「その理由は、～です。」⚫ データを出す「次のデータは、～を示しています。」50現代のソフトウェア開発では、複数の開発者が複数の機能を並行開発していくことが一般的になっています。ソフトウェアが大規模化し、求められる開発スピードも増しているからです。主張理由
Step④：わかりやすく、簡潔な文章で書く51
書くときの心構え⚫ 重要なことから書く⚫ （自分ではなく）読者の視点で書く⚫ 読者の行動をイメージしながら書くどんな人が、どんな情報を、どのように探すか⚫ 簡潔に、できるだけ短文で書く52
重要なことから書く53⚫ Before（理由 → 主張の順）ソフトウェアが大規模化し、求められる開発スピードも増しているため、現代のソフトウェア開発では、複数の開発者が複数の機能を並行開発していくことが一般的になっています。⚫ After（主張 → 理由の順）現代のソフトウェア開発では、複数の開発者が複数の機能を並行開発していくことが一般的になっています。ソフトウェアが大規模化し、求められる開発スピードも増しているからです。✓ ドキュメントは、一部しか読まれないことを前提に書く✓ 情報に優先度を付けて、優先度が高いことを先に書く✓ たとえば、主張（伝えたいこと）は理由よりも前に書くポイント
読者の視点で書く54⚫ BeforeGitHubでのプルリクエストの作成をトリガーにして、コードの自動テストを実行します。⚫ AfterGitHubでプルリクエストを作ると、書いたコードが自動的にテストされます。✓ 読者の視点で書くことが、読みやすさと、わかりやすさに繋がる✓ システムが主語になっていると、自分視点に置き換えながら読まなくてはならなくなるポイント
能動態と受動態を使い分ける55⚫ BeforeGitHubでプルリクエストを作成すると、コードの自動ビルドと自動テストを実行します。⚫ AfterGitHubでプルリクエストを作成すると、コードの自動ビルドと自動テストが実行されます。✓ 読者の視点で書くと、読者の操作は能動態、システムの動作は受動態になるポイント能動態受動態読み手の視点システムの視点
一文一義で書く⚫ Beforeソフトウェアが大規模化し、求められる開発スピードも増しているため、現代のソフトウェア開発では、複数の開発者が複数の機能を並行開発していくことが一般的になっています。⚫ Afterソフトウェアが大規模化し、求められる開発スピードも増しています。そのため、現代のソフトウェア開発では、複数の開発者が複数の機能を並行開発していくことが一般的になっています。56✓ 1つの文には、1つの事柄だけを書く✓ 1文に複数の事柄が詰め込まれていると、内容を整理しながら読まなくてはならなくなるポイント
一文を短くする57⚫ Before継続的インテグレーションを導入することで、ソフトウェアの品質を安定的に保つことができ、また、ソフトウェアのリリースに掛かる時間を短縮することができます。⚫ After継続的インテグレーションを導入することで、ソフトウェアの品質を安定的に保つことができ、保てます。また、ソフトウェアのリリースに掛かる時間を短縮することができます。も短縮できます。✓ 簡潔、短くを常に意識する✓ 「したがって」「また」などの接続詞も、不要なことが多い✓ 「（文の）わかりやすさと長短とは本質的には関係がない」（『日本語の作文技術』 12刷, 本田勝一, P.194）が、書き慣れていない人は「1文を短く」を常に意識すべきポイント
主語と述語の対応に気をつける58⚫ Before継続的デリバリーは、開発者によるアプリケーションへの変更に対して、バグがないか自動的にテストし、リポジトリにアップロードします。⚫ After継続的デリバリーは、開発者によるアプリケーションへの変更に対してバグがないか自動的にテストし、リポジトリにアップロードするプロセスです。✓ 主語と述語が一致しないと、意味が通らない文になる✓ 文が長くなると起こりがちなミスなので、意識して気を付けるポイント
修飾する側とされる側を近づける59⚫ BeforeDockerイメージは、docker buildコマンドを実行すると、Docker fileというファイルで指定した命令に従ってビルドされます。⚫ Afterdocker buildコマンドを実行すると、Docker fileというファイルで指定した命令に従ってDockerイメージがビルドされます。✓ 文が長くなるときは、修飾する側（主語や目的語）と 修飾される側（述語）を近づけると、読みやすくなるポイント
修飾部が複数あるとき60docker buildコマンドを実行すると、Docker fileというファイルで指定した命令に従って Dockerイメージが ビルドされます。Docker fileというファイルで指定した命令に従ってDockerイメージがビルドされます修飾する側 修飾される側✓ 修飾部が複数あるときは、長い修飾部から順に書くポイント
読点を適切に打つ61⚫ Beforeコードがマージされると、アプリケーションのビルドと単体テストと統合テストが自動的に実行されます。⚫ Afterコードがマージされると、アプリケーションのビルド、単体テストと、統合テストが自動的に実行されます。✓ 読みやすさのために、読点は特に重要✓ 読点を適切に打つことで、係り受けや並列関係がはっきりし、文章が読みやすくなるポイント
読点のパターン62例 説明Webサーバーにより、出力されるヘッダは異なります。 係り受けを明確にするために打つコードがマージされると、アプリケーションのビルド、単体テストと、統合テストが自動的に実行されます。並列関係を明確にするために打つdocker buildコマンドを実行すると、Dockerイメージがビルドされます。理由・条件・目的などを明確にするために打つAブランチをBブランチに、CブランチをDブランチにマージします。 句の区切りを明確にするために打つなお、モノリシックなアプリケーションにはこの設定は不要です。 接続詞の後ろに打つ（任意）
並列の情報には箇条書きを使う63⚫ Beforeコードがマージされると、アプリケーションのビルド、単体テストと、統合テストが自動的に実行されます。⚫ Afterコードがマージされると、アプリケーションに対して次の処理が自動で実行されます。⚫ ビルド⚫ 単体テスト⚫ 統合テスト✓ 並列の情報を並べるときは、箇条書きを活用すると、並列関係が視覚的にわかりやすくなるポイント
できるだけ具体的に書く64⚫ Before例1： ビルドからデプロイまでのサイクルを素早く回します。例2： メール通知の設定を確認してください。⚫ After例1： ビルドからデプロイまでのサイクルを、少なくとも1日1回、できれば1日複数回の頻度で回します。例2： メール通知が有効になっていることを確認してください。✓ 曖昧な表現は、書き手の意図通りに伝わらない✓ 具体的に書く努力をポイント
肯定形で書く65⚫ Beforeマージしたブランチは、残したままにしないでください。⚫ Afterマージしたブランチは、削除してください。✓ 否定表現は意味を曖昧にする✓ 肯定形で表現できる場合は、なるべく肯定形を使うポイント
二重否定を使わない66⚫ Beforeビルドが終わらないと、ロールバックできません。⚫ Afterビルドが終わると、ロールバックできます。✓ 否定表現は、1つの文に1つまで✓ 二重否定は文章をわかりづらくし、読者の混乱を招くポイント
「～の」は1文に2つまで⚫ BeforeGitHubのGUIからのPull RequestのRevertにより簡単にロールバックを行うことができます。⚫ AfterGitHubのGUIからPull RequestをRevertするだけで、簡単にロールバックできます。67✓ 「～の」が続くと読みづらくなる✓ 「～の」は、1文に多くて2つまでポイント
チェックシート✓ 冒頭に概要を書いていますか？✓ 一文一義で書いていますか？✓ 読者の視点で書いていますか？✓ 重要なことから書いていますか？✓ 文はこれ以上短くなりませんか？✓ 曖昧な表現はありませんか？✓ 係り受けは明確ですか？✓ 否定文は肯定形で書けませんか？✓ 修飾する側とされる側が離れ過ぎていませんか？68
ご清聴ありがとうございました本セッションが皆さまの情報発信に役立つことを願っています！69
naohiro_nakata
sue445
iotengineer22
oracle4engineer
megabitsenmzq
xibuka
hirosatogamo
ad5jp
asazutaiga
mapbox_jp
korodroid
kentosuzuki
ikuyamada
jonyablonski
paulrobertlloyd
shpigford
eileencodes
rasmusluckow
nonsquared
jnunemaker
ufuk
marcelosomers
stephaniewalter
mclloyd
addyosmani