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. 2 仲田 尚央 Nakata Naohiro @naoh_nak サイボウズ テクニカルライターとローカライズの職能マネージャー お仕事の内容: ⚫

    サイボウズ製品のUIテキストを書く ⚫ 製品のマニュアルやヘルプを書く ⚫ それらを他の言語に展開する(ローカライズ) 複業としてライティング講習もしています 5歳と2歳の子供がいます
  2. それぞれの要素に対して取る手段 13 Effectiveness 必要な情報を正しく得られる Satisfaction 不快さがなく、肯定的に 受け止められる Efficiency 効率よく理解できる •

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

    曖昧さを排し、明確に書く • できるだけ具体的に書く • 誤解なく読める文章で書く • 情報を適切に整理、構造化する • どこに何が書いてあるかをわかりやすくする • 簡潔で読みやすい文章で書く • 必要な情報だけを書く • 肯定的な表現で書く • ですます調で書く (過剰な敬語にはしない) “ユーザビリティーの高いドキュメント”を書けるようになる
  4. ドキュメントの階層 ドキュメントは階層構造が基本 ⚫ 1つのドキュメントで、1つのテーマを ⚫ 1つの見出しで、1つのサブテーマを ⚫ 1つの段落で、1つのトピックを 17 メインテーマ

    見出し 段落=トピック 段落=トピック 段落=トピック 見出し 段落=トピック 段落=トピック 段落=トピック サブテーマ サブテーマ 伝える情報を階層構造に整理する
  5. 順に説明を展開していく 24 スマートフォン Android Pixel Xperia Galaxy ・・・ iOS iPhone

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

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

    Pro Max iPhone Pro iPhone mini ・・・ 初めてのスマートフォン どれを選べばいいの? 種類が多すぎて… スマートフォンをOSや機種の具体例で分解
  8. スマートフォンを 使いこなす コミュニケーション ・・・ ・・・ ニュース ・・・ ・・・ 買い物 ナビ

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

    ゲーム 30 分解方法は、サブテーマごとに異なってもいい ただし、同じ枝の同階層での混在はダメ OSや機種の具体例で分解 用途の具体例で分解
  10. 読み手の予想通りに文章を展開する ⚫ 読み手の予想通りに文章を展開する ことで、読み手は一読で文章を理解で きるようになる ⚫ そのために、先に概要や全体像を伝え たあとで、そこで述べた順番のままに、 詳しい説明を展開していく 35

    CI/CDとは、 です。CI/CDには、 継続的インテグレーション、継続的デプロイ、継続 的デリバリーの3つの要素があります。 継続的インテグレーションとは 継続的デプロイとは 継続的デリバリーとは
  11. 記事の基本構成 ⚫ タイトルで、そのページのテーマを伝える ⚫ リード文で、これから何を述べるのかを伝 える ⚫ 次に、概要や全体像を伝える ⚫ さらに、サブテーマごとの詳細へと展開し

    ていく 36 タイトル(≒テーマ) 概要・全体像 見出し(任意) 見出し サブテーマ1 見出し サブテーマ2 リード文 ✓ 1つの記事の中でも階層構造をとる ポイント
  12. 38 CI/CD CI/CDとは 継続的インテグレーション ビルド 統合 テスト 継続的デリバリー 継続的デプロイ CI/CDの実践

    バージョン管理システム CI/CDパイプライン 実行環境 ココを1記事として 書いてみよう
  13. 記事で伝える情報を書き出す テーマ: CI/CDとは 伝えることを書き出した例: ⚫ CI/CDの概要 ⚫ なぜCI/CDが必要なのか ⚫ CI/CDのメリット

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

    ⚫ CI/CDのプロセス ⚫ 継続的インテグレーション ⚫ 継続的デリバリー ⚫ 継続的デプロイ ⚫ CI/CDパイプラインの流れ ⚫ CI/CDツールの紹介 40 ✓ 書き出した情報を階層化する ✓ 同じ階層は同じ粒度になるように ✓ 順番も意識する ⚫ 重要度で並べる ⚫ 時系列で並べる ⚫ 既知から未知へと並べる ポイント
  15. 見出しを決める 見出し構造(=アウトライン)の例: ⚫ CI/CDとは ⚫ CI/CDが必要になる背景 ⚫ アジャイル開発との関係 → 段落に

    ⚫ CI/CDのメリット → 段落に ⚫ CI/CDの3つのプロセス ⚫ 継続的インテグレーション ⚫ 継続的デリバリー ⚫ 継続的デプロイ ⚫ CI/CDパイプラインの流れ → 段落に ⚫ CI/CDに必要なツール 41 ✓ 見出しを見るだけで読者が次の情報を読み 取れる言葉にする: ⚫ 説明の流れ ⚫ 見出しに続く本文に何が書かれているか ⚫ どのようなときに読む必要があるのか ✓ 書く内容が少なければ、見出しを外し、段落 へと格下げする ポイント
  16. トピックを意識する ⚫ 文章を書き始める前に、段落単位で文章 の構成を組む ⚫ 1つの段落が1つのトピック(話題)になる ⚫ 1つの段落は3文~8文程度 ⚫ Webでは2文~5文程度が目安

    ⚫ 短過ぎると、主張の根拠が不足する ⚫ 長過ぎると、読みづらくなる 43 トピック1 見出し トピック2 トピック3 見出し トピック1 ・・・
  17. トピックを意識する効果 ⚫ 読み手 ⚫ 順序立てて話題が進むので、頭に入りやすい ⚫ 段落単位で読み飛ばしができる ⚫ 書き手 ⚫

    書くべきトピックが決まっていると、書きやすい ⚫ 情報の過不足が視覚的にわかる 44
  18. テーマをトピックに分解する 46 ⚫ テーマ CI/CDのプロセス ⚫ トピック ⚫ 継続的インテグレーションについて ⚫

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

    加えると、変更が競合する可能性があること ⚫ CI/CDは、そのようなリスクを低減すること トピックごとの関係を考える 47 並列のトピック 順列のトピック ⚫ テーマ CI/CDのプロセス ⚫ トピック ⚫ 継続的インテグレーションについて ⚫ 継続的デリバリーについて ⚫ 継続的デプロイについて
  20. トピックの展開 トピックを展開していく代表的なパターン: ⚫ 詳細を述べる 「つまり、~ということです。」 ⚫ 具体例を挙げる 「たとえば、~があります。」 ⚫ 理由を述べる

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

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

    ✓ 読者の視点で書くことが、読みやすさと、 わかりやすさに繋がる ✓ システムが主語になっていると、自分視点 に置き換えながら読まなくてはならなくなる ポイント
  23. 一文一義で書く ⚫ Before ソフトウェアが大規模化し、求められる開発スピードも増 しているため、現代のソフトウェア開発では、複数の開発 者が複数の機能を並行開発していくことが一般的になっ ています。 ⚫ After ソフトウェアが大規模化し、求められる開発スピードも増

    しています。そのため、現代のソフトウェア開発では、複 数の開発者が複数の機能を並行開発していくことが一 般的になっています。 56 ✓ 1つの文には、1つの事柄だけを書く ✓ 1文に複数の事柄が詰め込まれていると、 内容を整理しながら読まなくてはならなく なる ポイント
  24. 一文を短くする 57 ⚫ Before 継続的インテグレーションを導入することで、ソフトウェア の品質を安定的に保つことができ、また、ソフトウェアのリ リースに掛かる時間を短縮することができます。 ⚫ After 継続的インテグレーションを導入することで、ソフトウェア

    の品質を安定的に保つことができ、保てます。また、ソフ トウェアのリリースに掛かる時間を短縮することができます。 も短縮できます。 ✓ 簡潔、短くを常に意識する ✓ 「したがって」「また」などの接続詞も、不要 なことが多い ✓ 「(文の)わかりやすさと長短とは本質的 には関係がない」(『日本語の作文技術』 12刷, 本 田勝一, P.194)が、書き慣れていない人は 「1文を短く」を常に意識すべき ポイント
  25. 主語と述語の対応に気をつける 58 ⚫ Before 継続的デリバリーは、開発者によるアプリケーションへの 変更に対して、バグがないか自動的にテストし、リポジト リにアップロードします。 ⚫ After 継続的デリバリーは、開発者によるアプリケーションへの

    変更に対してバグがないか自動的にテストし、リポジトリ にアップロードするプロセスです。 ✓ 主語と述語が一致しないと、意味が通ら ない文になる ✓ 文が長くなると起こりがちなミスなので、 意識して気を付ける ポイント
  26. 修飾する側とされる側を近づける 59 ⚫ Before Dockerイメージは、docker buildコマンドを実行する と、Docker fileというファイルで指定した命令に従ってビ ルドされます。 ⚫

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

    fileというファイルで指定した命令に従って Dockerイメージが ビルドされます 修飾する側 修飾される側 ✓ 修飾部が複数あるときは、長い修飾部か ら順に書く ポイント
  28. 読点のパターン 62 例 説明 Webサーバーにより、出力されるヘッダは異なります。 係り受けを明確にするために打つ コードがマージされると、アプリケーションのビルド、単体テストと、 統合テストが自動的に実行されます。 並列関係を明確にするために打つ docker

    buildコマンドを実行すると、Dockerイメージがビルド されます。 理由・条件・目的などを明確にするために打つ AブランチをBブランチに、CブランチをDブランチにマージします。 句の区切りを明確にするために打つ なお、モノリシックなアプリケーションにはこの設定は不要です。 接続詞の後ろに打つ(任意)
  29. できるだけ具体的に書く 64 ⚫ Before 例1: ビルドからデプロイまでのサイクルを素早く回します。 例2: メール通知の設定を確認してください。 ⚫ After

    例1: ビルドからデプロイまでのサイクルを、少なくとも1日 1回、できれば1日複数回の頻度で回します。 例2: メール通知が有効になっていることを確認してく ださい。 ✓ 曖昧な表現は、書き手の意図通りに伝 わらない ✓ 具体的に書く努力を ポイント
  30. 「~の」は1文に2つまで ⚫ Before GitHubのGUIからのPull RequestのRevertにより簡 単にロールバックを行うことができます。 ⚫ After GitHubのGUIからPull RequestをRevertするだけで、

    簡単にロールバックできます。 67 ✓ 「~の」が続くと読みづらくなる ✓ 「~の」は、1文に多くて2つまで ポイント
  31. チェックシート ✓ 冒頭に概要を書いていますか? ✓ 一文一義で書いていますか? ✓ 読者の視点で書いていますか? ✓ 重要なことから書いていますか? ✓

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