Share
Embed
技術をわかりやすく伝えるためテクニカルライティング
技術をわかりやすく伝えるためのテクニックとしての「テクニカルライティング」を学べます。Developers Summit 2023の登壇資料。開発者・エンジニアの方向け。
https://twitter.com/naoh_nak
Naohiro Nakata
February 11, 2023
Transcript
67 slides
-
2 仲田 尚央 Nakata Naohiro @naoh_nak サイボウズ テクニカルライターとローカライズの職能マネージャー お仕事の内容: ⚫
サイボウズ製品のUIテキストを書く ⚫ 製品のマニュアルやヘルプを書く ⚫ それらを他の言語に展開する(ローカライズ) 複業としてライティング講習もしています 5歳と2歳の子供がいます -
本講の流れ 1. テクニカルライティングの基本的な考え方を知る 2. 情報を適切に整理するためのコツを知る 3. 文章の構成を組むためのコツを知る 4. わかりやすい文章を書くためのコツを知る 5
✓ 本講では、文章の書き方だけでなく、情報をどう整理するかにも重点を置いています。 -
ドキュメントの前提2 - 情報の探し方も違う 9 業務マニュアル 作業Aの手順を知りたい。 入社したばかりで何もわからん。 今度担当することになった業務Bにつ いて、一通り全部知っておきたい。 インストールが必要なツールを知りたい。
・・・ 知りたいことが明確 知りたいことが曖昧 網羅的に知りたい -
それぞれの要素に対して取る手段 13 Effectiveness 必要な情報を正しく得られる Satisfaction 不快さがなく、肯定的に 受け止められる Efficiency 効率よく理解できる •
曖昧さを排し、明確に書く • できるだけ具体的に書く • 誤解なく読める文章で書く • 情報を適切に整理、構造化する • どこに何が書いてあるかをわかりやすくする • 簡潔で読みやすい文章で書く • 必要な情報だけを書く • 肯定的な表現で書く • ですます調で書く (過剰な敬語にはしない) -
それぞれの要素に対して取る手段 14 Effectiveness 必要な情報を正しく得られる Satisfaction 不快さがなく、肯定的に 受け止められる Efficiency 効率よく理解できる •
曖昧さを排し、明確に書く • できるだけ具体的に書く • 誤解なく読める文章で書く • 情報を適切に整理、構造化する • どこに何が書いてあるかをわかりやすくする • 簡潔で読みやすい文章で書く • 必要な情報だけを書く • 肯定的な表現で書く • ですます調で書く (過剰な敬語にはしない) “ユーザビリティーの高いドキュメント”を書けるようになる -
ドキュメントの階層 ドキュメントは階層構造が基本 ⚫ 1つのドキュメントで、1つのテーマを ⚫ 1つの見出しで、1つのサブテーマを ⚫ 1つの段落で、1つのトピックを 17 メインテーマ
見出し 段落=トピック 段落=トピック 段落=トピック 見出し 段落=トピック 段落=トピック 段落=トピック サブテーマ サブテーマ 伝える情報を階層構造に整理する -
19 伝えるテーマ テーマ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 カテゴリー ページ 見出し -
全体から部分へと分解する 22 CI/CD CI/CDとは 継続的インテグレーション ビルド 統合 テスト 継続的デリバリー 継続的デプロイ
CI/CDの実践 バージョン管理システム CI/CDパイプライン 実行環境 -
概要から具体へと分解する 23 スマートフォン Android Pixel Xperia Galaxy ・・・ iOS iPhone
Pro Max iPhone Pro iPhone mini ・・・ -
順に説明を展開していく 24 スマートフォン Android Pixel Xperia Galaxy ・・・ iOS iPhone
Pro Max iPhone Pro iPhone mini ・・・ 段階を追って知識を付け加えて いくことが、わかりやすさに繋がる -
情報を適切に分解すると、読者が情報を探しやすくなる 25 スマートフォン Android Pixel Xperia Galaxy ・・・ iOS iPhone
Pro Max iPhone Pro iPhone mini ・・・ 前知識がない人は、最初 から読み、興味を持った 項目へと進む 特定の知識が欲しい人は、 その項だけを読む さわりだけを知りたい人は、 概要だけを読む どこに何が書いてあるかがわかるよう、適切なタイトルと見出しを付けよう -
28 スマートフォンを 買う Android Pixel Xperia Galaxy ・・・ iOS iPhone
Pro Max iPhone Pro iPhone mini ・・・ 初めてのスマートフォン どれを選べばいいの? 種類が多すぎて… スマートフォンをOSや機種の具体例で分解 -
スマートフォンを 使いこなす コミュニケーション ・・・ ・・・ ニュース ・・・ ・・・ 買い物 ナビ
ゲーム ・・・ 29 スマートフォン買ったよ! 使いこなしたい スマートフォンを用途の具体例で分解 -
スマートフォン スマートフォンを買う Android iOS スマートフォンを 使いこなす コミュニケーション ニュース 買い物 ナビ
ゲーム 30 分解方法は、サブテーマごとに異なってもいい ただし、同じ枝の同階層での混在はダメ OSや機種の具体例で分解 用途の具体例で分解 -
アウトラインとは ⚫ アウトラインとは:物事のあらまし。大筋。概略。 ⚫ ドキュメントにおけるアウトラインとは、章・節・項などの見出しを階層的に 設定、表示したもの ⚫ 2つの役割を持つ: ⚫ あらかじめ説明の流れを読み手に掴ませ、心の準備をさせる役割
⚫ 必要とする情報がどこに書かれているか、探しやすくする役割 34 -
読み手の予想通りに文章を展開する ⚫ 読み手の予想通りに文章を展開する ことで、読み手は一読で文章を理解で きるようになる ⚫ そのために、先に概要や全体像を伝え たあとで、そこで述べた順番のままに、 詳しい説明を展開していく 35
CI/CDとは、 です。CI/CDには、 継続的インテグレーション、継続的デプロイ、継続 的デリバリーの3つの要素があります。 継続的インテグレーションとは 継続的デプロイとは 継続的デリバリーとは -
記事の基本構成 ⚫ タイトルで、そのページのテーマを伝える ⚫ リード文で、これから何を述べるのかを伝 える ⚫ 次に、概要や全体像を伝える ⚫ さらに、サブテーマごとの詳細へと展開し
ていく 36 タイトル(≒テーマ) 概要・全体像 見出し(任意) 見出し サブテーマ1 見出し サブテーマ2 リード文 ✓ 1つの記事の中でも階層構造をとる ポイント -
38 CI/CD CI/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 ✓ 見出しを見るだけで読者が次の情報を読み 取れる言葉にする: ⚫ 説明の流れ ⚫ 見出しに続く本文に何が書かれているか ⚫ どのようなときに読む必要があるのか ✓ 書く内容が少なければ、見出しを外し、段落 へと格下げする ポイント -
トピックを意識する ⚫ 文章を書き始める前に、段落単位で文章 の構成を組む ⚫ 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のプロセス ⚫ トピック ⚫ 継続的インテグレーションについて ⚫ 継続的デリバリーについて ⚫ 継続的デプロイについて -
順列のトピックを詳細へと展開する 49 順列の情報は既知から未知へと順を追って理解できるように書く 現代のソフトウェア開発では、複数の開発者が複数の機能を並行開発していくことが一般 的になっています。ソフトウェアが大規模化し、求められる開発スピードも増しているからです。 複数の開発者がコードを追加したりライブラリーを追加したりすると、それらの変更が競合した り、依存関係が発生したりすることがあります。開発者のローカルでの開発が長く続けば続く ほど、コードをマージしたときに競合や不具合が発生するリスクが高まります。 このようなリスクを低減するため、CI/CDと呼ばれる開発プロセスでは、開発者は共有リポジ トリーに継続的にコミットします。コミットのたびにビルドとテストを自動的に実行することで、
コードの品質を安定的に保ちます。多くの場合、1日に複数回もの高頻度でビルドとテスト のサイクルを回します。 トピック① トピック② トピック③ -
トピックの展開 トピックを展開していく代表的なパターン: ⚫ 詳細を述べる 「つまり、~ということです。」 ⚫ 具体例を挙げる 「たとえば、~があります。」 ⚫ 理由を述べる
「その理由は、~です。」 ⚫ データを出す 「次のデータは、~を示しています。」 50 現代のソフトウェア開発では、複数の開発者が 複数の機能を並行開発していくことが一般的 になっています。ソフトウェアが大規模化し、求 められる開発スピードも増しているからです。 主張 理由 -
重要なことから書く 53 ⚫ Before(理由 → 主張の順) ソフトウェアが大規模化し、求められる開発スピードも増してい るため、現代のソフトウェア開発では、複数の開発者が複数 の機能を並行開発していくことが一般的になっています。 ⚫
After(主張 → 理由の順) 現代のソフトウェア開発では、複数の開発者が複数の機能を 並行開発していくことが一般的になっています。ソフトウェアが 大規模化し、求められる開発スピードも増しているからです。 ✓ ドキュメントは、一部しか読まれないことを 前提に書く ✓ 情報に優先度を付けて、優先度が高い ことを先に書く ✓ たとえば、主張(伝えたいこと)は理由よ りも前に書く ポイント -
読者の視点で書く 54 ⚫ Before GitHubでのプルリクエストの作成をトリガーにして、コード の自動テストを実行します。 ⚫ After GitHubでプルリクエストを作ると、書いたコードが自動的 にテストされます。
✓ 読者の視点で書くことが、読みやすさと、 わかりやすさに繋がる ✓ システムが主語になっていると、自分視点 に置き換えながら読まなくてはならなくなる ポイント -
能動態と受動態を使い分ける 55 ⚫ Before GitHubでプルリクエストを作成すると、コードの自動ビル ドと自動テストを実行します。 ⚫ After GitHubでプルリクエストを作成すると、コードの自動ビル ドと自動テストが実行されます。
✓ 読者の視点で書くと、読者の操作は能動 態、システムの動作は受動態になる ポイント 能動態 受動態 読み手の視点 システムの視点 -
一文一義で書く ⚫ Before ソフトウェアが大規模化し、求められる開発スピードも増 しているため、現代のソフトウェア開発では、複数の開発 者が複数の機能を並行開発していくことが一般的になっ ています。 ⚫ After ソフトウェアが大規模化し、求められる開発スピードも増
しています。そのため、現代のソフトウェア開発では、複 数の開発者が複数の機能を並行開発していくことが一 般的になっています。 56 ✓ 1つの文には、1つの事柄だけを書く ✓ 1文に複数の事柄が詰め込まれていると、 内容を整理しながら読まなくてはならなく なる ポイント -
一文を短くする 57 ⚫ Before 継続的インテグレーションを導入することで、ソフトウェア の品質を安定的に保つことができ、また、ソフトウェアのリ リースに掛かる時間を短縮することができます。 ⚫ After 継続的インテグレーションを導入することで、ソフトウェア
の品質を安定的に保つことができ、保てます。また、ソフ トウェアのリリースに掛かる時間を短縮することができます。 も短縮できます。 ✓ 簡潔、短くを常に意識する ✓ 「したがって」「また」などの接続詞も、不要 なことが多い ✓ 「(文の)わかりやすさと長短とは本質的 には関係がない」(『日本語の作文技術』 12刷, 本 田勝一, P.194)が、書き慣れていない人は 「1文を短く」を常に意識すべき ポイント -
主語と述語の対応に気をつける 58 ⚫ Before 継続的デリバリーは、開発者によるアプリケーションへの 変更に対して、バグがないか自動的にテストし、リポジト リにアップロードします。 ⚫ After 継続的デリバリーは、開発者によるアプリケーションへの
変更に対してバグがないか自動的にテストし、リポジトリ にアップロードするプロセスです。 ✓ 主語と述語が一致しないと、意味が通ら ない文になる ✓ 文が長くなると起こりがちなミスなので、 意識して気を付ける ポイント -
修飾する側とされる側を近づける 59 ⚫ Before Dockerイメージは、docker buildコマンドを実行する と、Docker fileというファイルで指定した命令に従ってビ ルドされます。 ⚫
After docker buildコマンドを実行すると、Docker fileという ファイルで指定した命令に従ってDockerイメージがビ ルドされます。 ✓ 文が長くなるときは、修飾する側(主語 や目的語)と 修飾される側(述語)を 近づけると、読みやすくなる ポイント -
修飾部が複数あるとき 60 docker 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つまで ⚫ Before GitHubのGUIからのPull RequestのRevertにより簡 単にロールバックを行うことができます。 ⚫ After GitHubのGUIからPull RequestをRevertするだけで、
簡単にロールバックできます。 67 ✓ 「~の」が続くと読みづらくなる ✓ 「~の」は、1文に多くて2つまで ポイント -
チェックシート ✓ 冒頭に概要を書いていますか? ✓ 一文一義で書いていますか? ✓ 読者の視点で書いていますか? ✓ 重要なことから書いていますか? ✓
文はこれ以上短くなりませんか? ✓ 曖昧な表現はありませんか? ✓ 係り受けは明確ですか? ✓ 否定文は肯定形で書けませんか? ✓ 修飾する側とされる側が離れ過ぎていませんか? 68