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

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

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

技術をわかりやすく伝えるためのテクニックとしての「テクニカルライティング」を学べます。Developers Summit 2023の登壇資料。開発者・エンジニアの方向け。
https://twitter.com/naoh_nak

Naohiro Nakata

February 11, 2023
Tweet

More Decks by Naohiro Nakata

Other Decks in Technology

Transcript

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

    View Slide

  2. 2
    仲田 尚央
    Nakata Naohiro
    @naoh_nak
    サイボウズ
    テクニカルライターとローカライズの職能マネージャー
    お仕事の内容:
    ⚫ サイボウズ製品のUIテキストを書く
    ⚫ 製品のマニュアルやヘルプを書く
    ⚫ それらを他の言語に展開する(ローカライズ)
    複業としてライティング講習もしています
    5歳と2歳の子供がいます

    View Slide

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

    View Slide

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

    View Slide

  5. 本講の流れ
    1. テクニカルライティングの基本的な考え方を知る
    2. 情報を適切に整理するためのコツを知る
    3. 文章の構成を組むためのコツを知る
    4. わかりやすい文章を書くためのコツを知る
    5
    ✓ 本講では、文章の書き方だけでなく、情報をどう整理するかにも重点を置いています。

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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



    View Slide

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

    View Slide

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

    View Slide

  13. それぞれの要素に対して取る手段
    13
    Effectiveness
    必要な情報を正しく得られる
    Satisfaction
    不快さがなく、肯定的に
    受け止められる
    Efficiency
    効率よく理解できる
    • 曖昧さを排し、明確に書く
    • できるだけ具体的に書く
    • 誤解なく読める文章で書く
    • 情報を適切に整理、構造化する
    • どこに何が書いてあるかをわかりやすくする
    • 簡潔で読みやすい文章で書く
    • 必要な情報だけを書く
    • 肯定的な表現で書く
    • ですます調で書く
    (過剰な敬語にはしない)

    View Slide

  14. それぞれの要素に対して取る手段
    14
    Effectiveness
    必要な情報を正しく得られる
    Satisfaction
    不快さがなく、肯定的に
    受け止められる
    Efficiency
    効率よく理解できる
    • 曖昧さを排し、明確に書く
    • できるだけ具体的に書く
    • 誤解なく読める文章で書く
    • 情報を適切に整理、構造化する
    • どこに何が書いてあるかをわかりやすくする
    • 簡潔で読みやすい文章で書く
    • 必要な情報だけを書く
    • 肯定的な表現で書く
    • ですます調で書く
    (過剰な敬語にはしない)
    “ユーザビリティーの高いドキュメント”を書けるようになる

    View Slide

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

    View Slide

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

    View Slide

  17. ドキュメントの階層
    ドキュメントは階層構造が基本
    ⚫ 1つのドキュメントで、1つのテーマを
    ⚫ 1つの見出しで、1つのサブテーマを
    ⚫ 1つの段落で、1つのトピックを
    17
    メインテーマ
    見出し
    段落=トピック
    段落=トピック
    段落=トピック
    見出し
    段落=トピック
    段落=トピック
    段落=トピック
    サブテーマ
    サブテーマ
    伝える情報を階層構造に整理する

    View Slide

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

    View Slide

  19. 19
    伝えるテーマ
    テーマ1
    テーマ1-1
    テーマ1-1-1
    テーマ1-1-2
    テーマ1-2
    テーマ2
    テーマ2-1
    テーマ2-2
    概要
    全体
    具体
    部分
    具体例で分解
    構成要素で分解

    View Slide

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

    View Slide

  21. Webの場合
    21
    伝えるテーマ
    テーマ1
    テーマ1-1
    テーマ1-1-1
    テーマ1-1-2
    テーマ1-2
    テーマ2
    テーマ2-1
    テーマ2-2
    カテゴリー ページ 見出し

    View Slide

  22. 全体から部分へと分解する
    22
    CI/CD
    CI/CDとは
    継続的インテグレーション
    ビルド
    統合
    テスト
    継続的デリバリー
    継続的デプロイ
    CI/CDの実践
    バージョン管理システム
    CI/CDパイプライン
    実行環境

    View Slide

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

    View Slide

  24. 順に説明を展開していく
    24
    スマートフォン
    Android
    Pixel
    Xperia
    Galaxy
    ・・・
    iOS
    iPhone Pro Max
    iPhone Pro
    iPhone mini
    ・・・
    段階を追って知識を付け加えて
    いくことが、わかりやすさに繋がる

    View Slide

  25. 情報を適切に分解すると、読者が情報を探しやすくなる
    25
    スマートフォン
    Android
    Pixel
    Xperia
    Galaxy
    ・・・
    iOS
    iPhone Pro Max
    iPhone Pro
    iPhone mini
    ・・・
    前知識がない人は、最初
    から読み、興味を持った
    項目へと進む
    特定の知識が欲しい人は、
    その項だけを読む
    さわりだけを知りたい人は、
    概要だけを読む
    どこに何が書いてあるかがわかるよう、適切なタイトルと見出しを付けよう

    View Slide

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

    View Slide

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

    View Slide

  28. 28
    スマートフォンを
    買う
    Android
    Pixel
    Xperia
    Galaxy
    ・・・
    iOS
    iPhone Pro Max
    iPhone Pro
    iPhone mini
    ・・・
    初めてのスマートフォン
    どれを選べばいいの?
    種類が多すぎて…
    スマートフォンをOSや機種の具体例で分解

    View Slide

  29. スマートフォンを
    使いこなす
    コミュニケーション
    ・・・
    ・・・
    ニュース
    ・・・
    ・・・
    買い物
    ナビ
    ゲーム
    ・・・
    29
    スマートフォン買ったよ!
    使いこなしたい
    スマートフォンを用途の具体例で分解

    View Slide

  30. スマートフォン
    スマートフォンを買う
    Android
    iOS
    スマートフォンを
    使いこなす
    コミュニケーション
    ニュース
    買い物
    ナビ
    ゲーム
    30
    分解方法は、サブテーマごとに異なってもいい
    ただし、同じ枝の同階層での混在はダメ
    OSや機種の具体例で分解
    用途の具体例で分解

    View Slide

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

    View Slide

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

    View Slide

  33. 読み手の予想通りに文章を展開する
    ⚫ 読み手の予想通りに文章を展開する
    ことで、読み手は一読で文章を理解で
    きるようになる
    ⚫ そのために、先に概要や全体像を伝え
    たあとで、そこで述べた順番のままに、
    詳しい説明を展開していく
    35
    CI/CDとは、 です。CI/CDには、
    継続的インテグレーション、継続的デプロイ、継続
    的デリバリーの3つの要素があります。
    継続的インテグレーションとは
    継続的デプロイとは
    継続的デリバリーとは

    View Slide

  34. 記事の基本構成
    ⚫ タイトルで、そのページのテーマを伝える
    ⚫ リード文で、これから何を述べるのかを伝
    える
    ⚫ 次に、概要や全体像を伝える
    ⚫ さらに、サブテーマごとの詳細へと展開し
    ていく
    36
    タイトル(≒テーマ)
    概要・全体像
    見出し(任意)
    見出し
    サブテーマ1
    見出し
    サブテーマ2
    リード文
    ✓ 1つの記事の中でも階層構造をとる
    ポイント

    View Slide

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

    View Slide

  36. 38
    CI/CD
    CI/CDとは
    継続的インテグレーション
    ビルド
    統合
    テスト
    継続的デリバリー
    継続的デプロイ
    CI/CDの実践
    バージョン管理システム
    CI/CDパイプライン
    実行環境
    ココを1記事として
    書いてみよう

    View Slide

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

    View Slide

  38. 書き出した情報を整理する
    伝える情報を整理した例:
    ⚫ CI/CDの概要
    ⚫ なぜCI/CDが必要なのか
    ⚫ アジャイル開発との関係
    ⚫ CI/CDのメリット
    ⚫ CI/CDのプロセス
    ⚫ 継続的インテグレーション
    ⚫ 継続的デリバリー
    ⚫ 継続的デプロイ
    ⚫ CI/CDパイプラインの流れ
    ⚫ CI/CDツールの紹介
    40
    ✓ 書き出した情報を階層化する
    ✓ 同じ階層は同じ粒度になるように
    ✓ 順番も意識する
    ⚫ 重要度で並べる
    ⚫ 時系列で並べる
    ⚫ 既知から未知へと並べる
    ポイント

    View Slide

  39. 見出しを決める
    見出し構造(=アウトライン)の例:
    ⚫ CI/CDとは
    ⚫ CI/CDが必要になる背景
    ⚫ アジャイル開発との関係 → 段落に
    ⚫ CI/CDのメリット → 段落に
    ⚫ CI/CDの3つのプロセス
    ⚫ 継続的インテグレーション
    ⚫ 継続的デリバリー
    ⚫ 継続的デプロイ
    ⚫ CI/CDパイプラインの流れ → 段落に
    ⚫ CI/CDに必要なツール
    41
    ✓ 見出しを見るだけで読者が次の情報を読み
    取れる言葉にする:
    ⚫ 説明の流れ
    ⚫ 見出しに続く本文に何が書かれているか
    ⚫ どのようなときに読む必要があるのか
    ✓ 書く内容が少なければ、見出しを外し、段落
    へと格下げする
    ポイント

    View Slide

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

    View Slide

  41. トピックを意識する
    ⚫ 文章を書き始める前に、段落単位で文章
    の構成を組む
    ⚫ 1つの段落が1つのトピック(話題)になる
    ⚫ 1つの段落は3文~8文程度
    ⚫ Webでは2文~5文程度が目安
    ⚫ 短過ぎると、主張の根拠が不足する
    ⚫ 長過ぎると、読みづらくなる
    43
    トピック1
    見出し
    トピック2
    トピック3
    見出し
    トピック1
    ・・・

    View Slide

  42. トピックを意識する効果
    ⚫ 読み手
    ⚫ 順序立てて話題が進むので、頭に入りやすい
    ⚫ 段落単位で読み飛ばしができる
    ⚫ 書き手
    ⚫ 書くべきトピックが決まっていると、書きやすい
    ⚫ 情報の過不足が視覚的にわかる
    44

    View Slide

  43. テーマ > トピック > 文章 の流れ
    1. テーマをトピックに分解する
    2. トピックごとの関係を考える
    3. 各トピックの詳細(文章)を書く
    45

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

  48. トピックの展開
    トピックを展開していく代表的なパターン:
    ⚫ 詳細を述べる
    「つまり、~ということです。」
    ⚫ 具体例を挙げる
    「たとえば、~があります。」
    ⚫ 理由を述べる
    「その理由は、~です。」
    ⚫ データを出す
    「次のデータは、~を示しています。」
    50
    現代のソフトウェア開発では、複数の開発者が
    複数の機能を並行開発していくことが一般的
    になっています。ソフトウェアが大規模化し、求
    められる開発スピードも増しているからです。
    主張
    理由

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

  52. 読者の視点で書く
    54
    ⚫ Before
    GitHubでのプルリクエストの作成をトリガーにして、コード
    の自動テストを実行します。
    ⚫ After
    GitHubでプルリクエストを作ると、書いたコードが自動的
    にテストされます。
    ✓ 読者の視点で書くことが、読みやすさと、
    わかりやすさに繋がる
    ✓ システムが主語になっていると、自分視点
    に置き換えながら読まなくてはならなくなる
    ポイント

    View Slide

  53. 能動態と受動態を使い分ける
    55
    ⚫ Before
    GitHubでプルリクエストを作成すると、コードの自動ビル
    ドと自動テストを実行します。
    ⚫ After
    GitHubでプルリクエストを作成すると、コードの自動ビル
    ドと自動テストが実行されます。
    ✓ 読者の視点で書くと、読者の操作は能動
    態、システムの動作は受動態になる
    ポイント
    能動態
    受動態
    読み手の視点
    システムの視点

    View Slide

  54. 一文一義で書く
    ⚫ Before
    ソフトウェアが大規模化し、求められる開発スピードも増
    しているため、現代のソフトウェア開発では、複数の開発
    者が複数の機能を並行開発していくことが一般的になっ
    ています。
    ⚫ After
    ソフトウェアが大規模化し、求められる開発スピードも増
    しています。そのため、現代のソフトウェア開発では、複
    数の開発者が複数の機能を並行開発していくことが一
    般的になっています。
    56
    ✓ 1つの文には、1つの事柄だけを書く
    ✓ 1文に複数の事柄が詰め込まれていると、
    内容を整理しながら読まなくてはならなく
    なる
    ポイント

    View Slide

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

    View Slide

  56. 主語と述語の対応に気をつける
    58
    ⚫ Before
    継続的デリバリーは、開発者によるアプリケーションへの
    変更に対して、バグがないか自動的にテストし、リポジト
    リにアップロードします。
    ⚫ After
    継続的デリバリーは、開発者によるアプリケーションへの
    変更に対してバグがないか自動的にテストし、リポジトリ
    にアップロードするプロセスです。
    ✓ 主語と述語が一致しないと、意味が通ら
    ない文になる
    ✓ 文が長くなると起こりがちなミスなので、
    意識して気を付ける
    ポイント

    View Slide

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

    View Slide

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

    View Slide

  59. 読点を適切に打つ
    61
    ⚫ Before
    コードがマージされると、アプリケーションのビルドと単体テ
    ストと統合テストが自動的に実行されます。
    ⚫ After
    コードがマージされると、アプリケーションのビルド、単体テ
    ストと、統合テストが自動的に実行されます。
    ✓ 読みやすさのために、読点は特に重要
    ✓ 読点を適切に打つことで、係り受けや並列
    関係がはっきりし、文章が読みやすくなる
    ポイント

    View Slide

  60. 読点のパターン
    62
    例 説明
    Webサーバーにより、出力されるヘッダは異なります。 係り受けを明確にするために打つ
    コードがマージされると、アプリケーションのビルド、単体テストと、
    統合テストが自動的に実行されます。
    並列関係を明確にするために打つ
    docker buildコマンドを実行すると、Dockerイメージがビルド
    されます。
    理由・条件・目的などを明確にするために打つ
    AブランチをBブランチに、CブランチをDブランチにマージします。 句の区切りを明確にするために打つ
    なお、モノリシックなアプリケーションにはこの設定は不要です。 接続詞の後ろに打つ(任意)

    View Slide

  61. 並列の情報には箇条書きを使う
    63
    ⚫ Before
    コードがマージされると、アプリケーションのビルド、単体テストと、
    統合テストが自動的に実行されます。
    ⚫ After
    コードがマージされると、アプリケーションに対して次の処理が自
    動で実行されます。
    ⚫ ビルド
    ⚫ 単体テスト
    ⚫ 統合テスト
    ✓ 並列の情報を並べるときは、箇条書きを
    活用すると、並列関係が視覚的にわかり
    やすくなる
    ポイント

    View Slide

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

    View Slide

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

    View Slide

  64. 二重否定を使わない
    66
    ⚫ Before
    ビルドが終わらないと、ロールバックできません。
    ⚫ After
    ビルドが終わると、ロールバックできます。
    ✓ 否定表現は、1つの文に1つまで
    ✓ 二重否定は文章をわかりづらくし、読者
    の混乱を招く
    ポイント

    View Slide

  65. 「~の」は1文に2つまで
    ⚫ Before
    GitHubのGUIからのPull RequestのRevertにより簡
    単にロールバックを行うことができます。
    ⚫ After
    GitHubのGUIからPull RequestをRevertするだけで、
    簡単にロールバックできます。
    67
    ✓ 「~の」が続くと読みづらくなる
    ✓ 「~の」は、1文に多くて2つまで
    ポイント

    View Slide

  66. チェックシート
    ✓ 冒頭に概要を書いていますか?
    ✓ 一文一義で書いていますか?
    ✓ 読者の視点で書いていますか?
    ✓ 重要なことから書いていますか?
    ✓ 文はこれ以上短くなりませんか?
    ✓ 曖昧な表現はありませんか?
    ✓ 係り受けは明確ですか?
    ✓ 否定文は肯定形で書けませんか?
    ✓ 修飾する側とされる側が離れ過ぎていませんか?
    68

    View Slide

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

    View Slide