技術をわかりやすく伝えるためテクニカルライティング

Transcript

1. 技術をわかりやすく伝えるための テクニカルライティング Developers Summit 2023 2月10日 17:45- 仲田 尚央@cybozu 1

2. 2 仲田 尚央 Nakata Naohiro @naoh_nak サイボウズ テクニカルライターとローカライズの職能マネージャー お仕事の内容： ⚫

   サイボウズ製品のUIテキストを書く ⚫ 製品のマニュアルやヘルプを書く ⚫ それらを他の言語に展開する（ローカライズ） 複業としてライティング講習もしています 5歳と2歳の子供がいます

3. はじめに、おことわり ⚫ 本セッションは、サイボウズのエンジニア向け 研修を編集したものです ⚫ 公開資料と内容が一部重複します 3 https://blog.speakerdeck.com/2022-most-viewed-decks/

4. 技術を伝えるということ ⚫ エンジニアには、知識や学びを共有しあう素晴らしい文化があります ⚫ しかし、いかに深い技術も、整理されないままでは読者に伝わりません ⚫ うまく整理されていても、それが適切に文章構成に反映されていなくては、 情報の価値は下がってしまいます 4

5. 本講の流れ 1. テクニカルライティングの基本的な考え方を知る 2. 情報を適切に整理するためのコツを知る 3. 文章の構成を組むためのコツを知る 4. わかりやすい文章を書くためのコツを知る 5

   ✓ 本講では、文章の書き方だけでなく、情報をどう整理するかにも重点を置いています。

6. エンジニアは「ドキュメント」を書く機会が多くあります。 6

7. ⚫ 仕様書を書く ⚫ 作業手順書を書く ⚫ 技術ブログを書く ⚫ 業務マニュアルを書く ⚫ リリースノートを書く

   ⚫ … 7

8. ドキュメントの前提1 - 求める情報が人によって違う 8 業務マニュアル 作業Aの手順を知りたい。 入社したばかりで何もわからん。 今度担当することになった業務Bにつ いて、一通り全部知っておきたい。 インストールが必要なツールを知りたい。

   ・・・

9. ドキュメントの前提2 - 情報の探し方も違う 9 業務マニュアル 作業Aの手順を知りたい。 入社したばかりで何もわからん。 今度担当することになった業務Bにつ いて、一通り全部知っておきたい。 インストールが必要なツールを知りたい。

   ・・・ 知りたいことが明確 知りたいことが曖昧 網羅的に知りたい

10. ドキュメントの前提3 – 一意に伝わる必要がある 10 ✕ ✕ ✕

11. ドキュメントの前提4 – 一部しか読まれない 11

12. テクニカルライティングの要素 12 Effectiveness 必要な情報を正しく得られる Satisfaction 不快さがなく、肯定的に 受け止められる Efficiency 効率よく理解できる ユーザビリティーの定義

    （ISO 9241-11）から

13. それぞれの要素に対して取る手段 13 Effectiveness 必要な情報を正しく得られる Satisfaction 不快さがなく、肯定的に 受け止められる Efficiency 効率よく理解できる •

    曖昧さを排し、明確に書く • できるだけ具体的に書く • 誤解なく読める文章で書く • 情報を適切に整理、構造化する • どこに何が書いてあるかをわかりやすくする • 簡潔で読みやすい文章で書く • 必要な情報だけを書く • 肯定的な表現で書く • ですます調で書く （過剰な敬語にはしない）

14. それぞれの要素に対して取る手段 14 Effectiveness 必要な情報を正しく得られる Satisfaction 不快さがなく、肯定的に 受け止められる Efficiency 効率よく理解できる •

    曖昧さを排し、明確に書く • できるだけ具体的に書く • 誤解なく読める文章で書く • 情報を適切に整理、構造化する • どこに何が書いてあるかをわかりやすくする • 簡潔で読みやすい文章で書く • 必要な情報だけを書く • 肯定的な表現で書く • ですます調で書く （過剰な敬語にはしない） “ユーザビリティーの高いドキュメント”を書けるようになる

15. テクニカルライティングの進め方 15 テーマ 見出し 段落 文章 ①伝える情報を整理する ②見出し単位でアウトラインを作る ③段落単位で文章の骨組みを作る ④わかりやすく、簡潔な文章で書く

16. Step①：伝える情報を整理する 16

17. ドキュメントの階層 ドキュメントは階層構造が基本 ⚫ 1つのドキュメントで、1つのテーマを ⚫ 1つの見出しで、1つのサブテーマを ⚫ 1つの段落で、1つのトピックを 17 メインテーマ

    見出し 段落＝トピック 段落＝トピック 段落＝トピック 見出し 段落＝トピック 段落＝トピック 段落＝トピック サブテーマ サブテーマ 伝える情報を階層構造に整理する

18. 整理の鉄則 18 概要から具体へ または 全体から部分へ

19. 19 伝えるテーマ テーマ1 テーマ1-1 テーマ1-1-1 テーマ1-1-2 テーマ1-2 テーマ2 テーマ2-1 テーマ2-2

    概要 全体 具体 部分 具体例で分解 構成要素で分解

20. 書籍や文書の場合 20 伝えるテーマ テーマ1 テーマ1-1 テーマ1-1-1 テーマ1-1-2 テーマ1-2 テーマ2 テーマ2-1

    テーマ2-2 章 節 項

21. Webの場合 21 伝えるテーマ テーマ1 テーマ1-1 テーマ1-1-1 テーマ1-1-2 テーマ1-2 テーマ2 テーマ2-1

    テーマ2-2 カテゴリー ページ 見出し

22. 全体から部分へと分解する 22 CI/CD CI/CDとは 継続的インテグレーション ビルド 統合 テスト 継続的デリバリー 継続的デプロイ

    CI/CDの実践 バージョン管理システム CI/CDパイプライン 実行環境

23. 概要から具体へと分解する 23 スマートフォン Android Pixel Xperia Galaxy ・・・ iOS iPhone

    Pro Max iPhone Pro iPhone mini ・・・

24. 順に説明を展開していく 24 スマートフォン Android Pixel Xperia Galaxy ・・・ iOS iPhone

    Pro Max iPhone Pro iPhone mini ・・・ 段階を追って知識を付け加えて いくことが、わかりやすさに繋がる

25. 情報を適切に分解すると、読者が情報を探しやすくなる 25 スマートフォン Android Pixel Xperia Galaxy ・・・ iOS iPhone

    Pro Max iPhone Pro iPhone mini ・・・ 前知識がない人は、最初 から読み、興味を持った 項目へと進む 特定の知識が欲しい人は、 その項だけを読む さわりだけを知りたい人は、 概要だけを読む どこに何が書いてあるかがわかるよう、適切なタイトルと見出しを付けよう

26. 分解には複数のやり方がある 26 スマートフォン コミュニケーション ・・・ ・・・ ニュース ・・・ ・・・ 買い物

    ナビ ゲーム ・・・

27. 情報の適切な分解って？ 27 NG：きれいに分解できる OK：読者の目的に合わせる

28. 28 スマートフォンを 買う Android Pixel Xperia Galaxy ・・・ iOS iPhone

    Pro Max iPhone Pro iPhone mini ・・・ 初めてのスマートフォン どれを選べばいいの？ 種類が多すぎて… スマートフォンをOSや機種の具体例で分解

29. スマートフォンを 使いこなす コミュニケーション ・・・ ・・・ ニュース ・・・ ・・・ 買い物 ナビ

    ゲーム ・・・ 29 スマートフォン買ったよ！ 使いこなしたい スマートフォンを用途の具体例で分解

30. スマートフォン スマートフォンを買う Android iOS スマートフォンを 使いこなす コミュニケーション ニュース 買い物 ナビ

    ゲーム 30 分解方法は、サブテーマごとに異なってもいい ただし、同じ枝の同階層での混在はダメ OSや機種の具体例で分解 用途の具体例で分解

31. Step②：アウトラインを作る 33

32. アウトラインとは ⚫ アウトラインとは：物事のあらまし。大筋。概略。 ⚫ ドキュメントにおけるアウトラインとは、章・節・項などの見出しを階層的に 設定、表示したもの ⚫ 2つの役割を持つ： ⚫ あらかじめ説明の流れを読み手に掴ませ、心の準備をさせる役割

    ⚫ 必要とする情報がどこに書かれているか、探しやすくする役割 34

33. 読み手の予想通りに文章を展開する ⚫ 読み手の予想通りに文章を展開する ことで、読み手は一読で文章を理解で きるようになる ⚫ そのために、先に概要や全体像を伝え たあとで、そこで述べた順番のままに、 詳しい説明を展開していく 35

    CI/CDとは、 です。CI/CDには、 継続的インテグレーション、継続的デプロイ、継続 的デリバリーの3つの要素があります。 継続的インテグレーションとは 継続的デプロイとは 継続的デリバリーとは

34. 記事の基本構成 ⚫ タイトルで、そのページのテーマを伝える ⚫ リード文で、これから何を述べるのかを伝 える ⚫ 次に、概要や全体像を伝える ⚫ さらに、サブテーマごとの詳細へと展開し

    ていく 36 タイトル（≒テーマ） 概要・全体像 見出し（任意） 見出し サブテーマ1 見出し サブテーマ2 リード文 ✓ 1つの記事の中でも階層構造をとる ポイント

35. アウトラインを作る流れ 1. 記事で伝える情報を書き出す 2. 書き出した情報を整理する 3. 見出しを決める 37

36. 38 CI/CD CI/CDとは 継続的インテグレーション ビルド 統合 テスト 継続的デリバリー 継続的デプロイ CI/CDの実践

    バージョン管理システム CI/CDパイプライン 実行環境 ココを1記事として 書いてみよう

37. 記事で伝える情報を書き出す テーマ： CI/CDとは 伝えることを書き出した例： ⚫ CI/CDの概要 ⚫ なぜCI/CDが必要なのか ⚫ CI/CDのメリット

    ⚫ アジャイル開発との関係 ⚫ CI/CDツールの紹介 ⚫ CI/CDパイプラインの流れ ⚫ 継続的インテグレーションとは ⚫ 継続的デリバリーとは ⚫ 継続的デプロイとは 39 ✓ テーマを分解してできた要素に加えて、記 事で伝えるべきことを書き出す ✓ この段階では、順番や言葉の表現などの 細かいことは気にしない ✓ 粒度もバラバラでOK ✓ 情報を漏れなく洗い出すことを重視する ポイント テーマを分解して できた要素

38. 書き出した情報を整理する 伝える情報を整理した例： ⚫ CI/CDの概要 ⚫ なぜCI/CDが必要なのか ⚫ アジャイル開発との関係 ⚫ CI/CDのメリット

    ⚫ CI/CDのプロセス ⚫ 継続的インテグレーション ⚫ 継続的デリバリー ⚫ 継続的デプロイ ⚫ CI/CDパイプラインの流れ ⚫ CI/CDツールの紹介 40 ✓ 書き出した情報を階層化する ✓ 同じ階層は同じ粒度になるように ✓ 順番も意識する ⚫ 重要度で並べる ⚫ 時系列で並べる ⚫ 既知から未知へと並べる ポイント

39. 見出しを決める 見出し構造（＝アウトライン）の例： ⚫ CI/CDとは ⚫ CI/CDが必要になる背景 ⚫ アジャイル開発との関係 → 段落に

    ⚫ CI/CDのメリット → 段落に ⚫ CI/CDの3つのプロセス ⚫ 継続的インテグレーション ⚫ 継続的デリバリー ⚫ 継続的デプロイ ⚫ CI/CDパイプラインの流れ → 段落に ⚫ CI/CDに必要なツール 41 ✓ 見出しを見るだけで読者が次の情報を読み 取れる言葉にする： ⚫ 説明の流れ ⚫ 見出しに続く本文に何が書かれているか ⚫ どのようなときに読む必要があるのか ✓ 書く内容が少なければ、見出しを外し、段落 へと格下げする ポイント

40. Step③：段落単位で文章の骨組みを作る 42

41. トピックを意識する ⚫ 文章を書き始める前に、段落単位で文章 の構成を組む ⚫ 1つの段落が1つのトピック（話題）になる ⚫ 1つの段落は3文～8文程度 ⚫ Webでは2文～5文程度が目安

    ⚫ 短過ぎると、主張の根拠が不足する ⚫ 長過ぎると、読みづらくなる 43 トピック1 見出し トピック2 トピック3 見出し トピック1 ・・・

42. トピックを意識する効果 ⚫ 読み手 ⚫ 順序立てて話題が進むので、頭に入りやすい ⚫ 段落単位で読み飛ばしができる ⚫ 書き手 ⚫

    書くべきトピックが決まっていると、書きやすい ⚫ 情報の過不足が視覚的にわかる 44

43. テーマ > トピック > 文章 の流れ 1. テーマをトピックに分解する 2. トピックごとの関係を考える

    3. 各トピックの詳細（文章）を書く 45

44. テーマをトピックに分解する 46 ⚫ テーマ CI/CDのプロセス ⚫ トピック ⚫ 継続的インテグレーションについて ⚫

    継続的デリバリーについて ⚫ 継続的デプロイについて ⚫ テーマ CI/CDが必要になる背景 ⚫ トピック ⚫ 現代のソフトウェア開発では、複数の開発者 による並行開発が必要になること ⚫ 複数の開発者がソフトウェアに同時に変更を 加えると、変更が競合する可能性があること ⚫ CI/CDは、そのようなリスクを低減すること

45. ⚫ テーマ CI/CDが必要になる背景 ⚫ トピック ⚫ 現代のソフトウェア開発では、複数の開発者 による並行開発が必要になること ⚫ 複数の開発者がソフトウェアに同時に変更を

    加えると、変更が競合する可能性があること ⚫ CI/CDは、そのようなリスクを低減すること トピックごとの関係を考える 47 並列のトピック 順列のトピック ⚫ テーマ CI/CDのプロセス ⚫ トピック ⚫ 継続的インテグレーションについて ⚫ 継続的デリバリーについて ⚫ 継続的デプロイについて

46. 並列のトピックを詳細へと展開する 継続的インテグレーションは、変更があったコードを自動的にビルド・統合・テストし、ソフトウェ アの品質を安定的に保つ開発プロセスです。ビルドからテストまでのサイクルを継続的に実行 することで、開発中に発生するバグを迅速に改修します。 継続的デリバリーは、継続的インテグレーションに続くプロセスとして、テストされたソフトウェアを テスト環境に自動的にデプロイするプロセスのことを言います。実際に触って使えるソフトウェア を継続的に提供することで、ソフトウェアの更新を、お客様に提供する前に検証できます。 継続的デプロイは、テストされたソフトウェアを本番環境にまで自動的にデプロイするプロセスで す。開発者による最新の変更を顧客が使用できるようにします。継続的デリバリーと継続的 デプロイの違いは、本番環境への適用に手動での承認を必要とするか否かという点です。

    48 並列の情報は同じ表現で書く トピック① トピック② トピック③

47. 順列のトピックを詳細へと展開する 49 順列の情報は既知から未知へと順を追って理解できるように書く 現代のソフトウェア開発では、複数の開発者が複数の機能を並行開発していくことが一般 的になっています。ソフトウェアが大規模化し、求められる開発スピードも増しているからです。 複数の開発者がコードを追加したりライブラリーを追加したりすると、それらの変更が競合した り、依存関係が発生したりすることがあります。開発者のローカルでの開発が長く続けば続く ほど、コードをマージしたときに競合や不具合が発生するリスクが高まります。 このようなリスクを低減するため、CI/CDと呼ばれる開発プロセスでは、開発者は共有リポジ トリーに継続的にコミットします。コミットのたびにビルドとテストを自動的に実行することで、

    コードの品質を安定的に保ちます。多くの場合、1日に複数回もの高頻度でビルドとテスト のサイクルを回します。 トピック① トピック② トピック③

48. トピックの展開 トピックを展開していく代表的なパターン： ⚫ 詳細を述べる 「つまり、～ということです。」 ⚫ 具体例を挙げる 「たとえば、～があります。」 ⚫ 理由を述べる

    「その理由は、～です。」 ⚫ データを出す 「次のデータは、～を示しています。」 50 現代のソフトウェア開発では、複数の開発者が 複数の機能を並行開発していくことが一般的 になっています。ソフトウェアが大規模化し、求 められる開発スピードも増しているからです。 主張 理由

49. Step④：わかりやすく、簡潔な文章で書く 51

50. 書くときの心構え ⚫ 重要なことから書く ⚫ （自分ではなく）読者の視点で書く ⚫ 読者の行動をイメージしながら書く どんな人が、どんな情報を、どのように探すか ⚫ 簡潔に、できるだけ短文で書く

    52

51. 重要なことから書く 53 ⚫ Before（理由 → 主張の順） ソフトウェアが大規模化し、求められる開発スピードも増してい るため、現代のソフトウェア開発では、複数の開発者が複数 の機能を並行開発していくことが一般的になっています。 ⚫

    After（主張 → 理由の順） 現代のソフトウェア開発では、複数の開発者が複数の機能を 並行開発していくことが一般的になっています。ソフトウェアが 大規模化し、求められる開発スピードも増しているからです。 ✓ ドキュメントは、一部しか読まれないことを 前提に書く ✓ 情報に優先度を付けて、優先度が高い ことを先に書く ✓ たとえば、主張（伝えたいこと）は理由よ りも前に書く ポイント

52. 読者の視点で書く 54 ⚫ Before GitHubでのプルリクエストの作成をトリガーにして、コード の自動テストを実行します。 ⚫ After GitHubでプルリクエストを作ると、書いたコードが自動的 にテストされます。

    ✓ 読者の視点で書くことが、読みやすさと、 わかりやすさに繋がる ✓ システムが主語になっていると、自分視点 に置き換えながら読まなくてはならなくなる ポイント

53. 能動態と受動態を使い分ける 55 ⚫ Before GitHubでプルリクエストを作成すると、コードの自動ビル ドと自動テストを実行します。 ⚫ After GitHubでプルリクエストを作成すると、コードの自動ビル ドと自動テストが実行されます。

    ✓ 読者の視点で書くと、読者の操作は能動 態、システムの動作は受動態になる ポイント 能動態 受動態 読み手の視点 システムの視点

54. 一文一義で書く ⚫ Before ソフトウェアが大規模化し、求められる開発スピードも増 しているため、現代のソフトウェア開発では、複数の開発 者が複数の機能を並行開発していくことが一般的になっ ています。 ⚫ After ソフトウェアが大規模化し、求められる開発スピードも増

    しています。そのため、現代のソフトウェア開発では、複 数の開発者が複数の機能を並行開発していくことが一 般的になっています。 56 ✓ 1つの文には、1つの事柄だけを書く ✓ 1文に複数の事柄が詰め込まれていると、 内容を整理しながら読まなくてはならなく なる ポイント

55. 一文を短くする 57 ⚫ Before 継続的インテグレーションを導入することで、ソフトウェア の品質を安定的に保つことができ、また、ソフトウェアのリ リースに掛かる時間を短縮することができます。 ⚫ After 継続的インテグレーションを導入することで、ソフトウェア

    の品質を安定的に保つことができ、保てます。また、ソフ トウェアのリリースに掛かる時間を短縮することができます。 も短縮できます。 ✓ 簡潔、短くを常に意識する ✓ 「したがって」「また」などの接続詞も、不要 なことが多い ✓ 「（文の）わかりやすさと長短とは本質的 には関係がない」（『日本語の作文技術』 12刷, 本 田勝一, P.194）が、書き慣れていない人は 「1文を短く」を常に意識すべき ポイント

56. 主語と述語の対応に気をつける 58 ⚫ Before 継続的デリバリーは、開発者によるアプリケーションへの 変更に対して、バグがないか自動的にテストし、リポジト リにアップロードします。 ⚫ After 継続的デリバリーは、開発者によるアプリケーションへの

    変更に対してバグがないか自動的にテストし、リポジトリ にアップロードするプロセスです。 ✓ 主語と述語が一致しないと、意味が通ら ない文になる ✓ 文が長くなると起こりがちなミスなので、 意識して気を付ける ポイント

57. 修飾する側とされる側を近づける 59 ⚫ Before Dockerイメージは、docker buildコマンドを実行する と、Docker fileというファイルで指定した命令に従ってビ ルドされます。 ⚫

    After docker buildコマンドを実行すると、Docker fileという ファイルで指定した命令に従ってDockerイメージがビ ルドされます。 ✓ 文が長くなるときは、修飾する側（主語 や目的語）と 修飾される側（述語）を 近づけると、読みやすくなる ポイント

58. 修飾部が複数あるとき 60 docker buildコマンドを実行すると、Docker fileとい うファイルで指定した命令に従って Dockerイメージ が ビルドされます。 Docker

    fileというファイルで指定した命令に従って Dockerイメージが ビルドされます 修飾する側 修飾される側 ✓ 修飾部が複数あるときは、長い修飾部か ら順に書く ポイント

59. 読点を適切に打つ 61 ⚫ Before コードがマージされると、アプリケーションのビルドと単体テ ストと統合テストが自動的に実行されます。 ⚫ After コードがマージされると、アプリケーションのビルド、単体テ ストと、統合テストが自動的に実行されます。

    ✓ 読みやすさのために、読点は特に重要 ✓ 読点を適切に打つことで、係り受けや並列 関係がはっきりし、文章が読みやすくなる ポイント

60. 読点のパターン 62 例 説明 Webサーバーにより、出力されるヘッダは異なります。 係り受けを明確にするために打つ コードがマージされると、アプリケーションのビルド、単体テストと、 統合テストが自動的に実行されます。 並列関係を明確にするために打つ docker

    buildコマンドを実行すると、Dockerイメージがビルド されます。 理由・条件・目的などを明確にするために打つ AブランチをBブランチに、CブランチをDブランチにマージします。 句の区切りを明確にするために打つ なお、モノリシックなアプリケーションにはこの設定は不要です。 接続詞の後ろに打つ（任意）

61. 並列の情報には箇条書きを使う 63 ⚫ Before コードがマージされると、アプリケーションのビルド、単体テストと、 統合テストが自動的に実行されます。 ⚫ After コードがマージされると、アプリケーションに対して次の処理が自 動で実行されます。

    ⚫ ビルド ⚫ 単体テスト ⚫ 統合テスト ✓ 並列の情報を並べるときは、箇条書きを 活用すると、並列関係が視覚的にわかり やすくなる ポイント

62. できるだけ具体的に書く 64 ⚫ Before 例1： ビルドからデプロイまでのサイクルを素早く回します。 例2： メール通知の設定を確認してください。 ⚫ After

    例1： ビルドからデプロイまでのサイクルを、少なくとも1日 1回、できれば1日複数回の頻度で回します。 例2： メール通知が有効になっていることを確認してく ださい。 ✓ 曖昧な表現は、書き手の意図通りに伝 わらない ✓ 具体的に書く努力を ポイント

63. 肯定形で書く 65 ⚫ Before マージしたブランチは、残したままにしないでください。 ⚫ After マージしたブランチは、削除してください。 ✓ 否定表現は意味を曖昧にする

    ✓ 肯定形で表現できる場合は、なるべく肯 定形を使う ポイント

64. 二重否定を使わない 66 ⚫ Before ビルドが終わらないと、ロールバックできません。 ⚫ After ビルドが終わると、ロールバックできます。 ✓ 否定表現は、1つの文に1つまで

    ✓ 二重否定は文章をわかりづらくし、読者 の混乱を招く ポイント

65. 「～の」は1文に2つまで ⚫ Before GitHubのGUIからのPull RequestのRevertにより簡 単にロールバックを行うことができます。 ⚫ After GitHubのGUIからPull RequestをRevertするだけで、

    簡単にロールバックできます。 67 ✓ 「～の」が続くと読みづらくなる ✓ 「～の」は、1文に多くて2つまで ポイント

66. チェックシート ✓ 冒頭に概要を書いていますか？ ✓ 一文一義で書いていますか？ ✓ 読者の視点で書いていますか？ ✓ 重要なことから書いていますか？ ✓

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

67. ご清聴ありがとうございました 本セッションが皆さまの情報発信に役立つことを願っています！ 69