美しい文章 / Beautiful Writings

エンジニアが技術書を執筆する際のテクニックや、気をつけるべきポイントをまとめました

Transcript

1. 美しい文章 Jan 18, 2019 | #techdo written by ariaki
2. 2 ariaki | @ariaki4dev
3. 3 「美しい文章」とは何でしょう？
4. 4 国境の長いトンネルを抜けると雪国であった。 夜の底が白くなった。信号所に汽車が止まった。 ──『雪国』川端康成
5. 5 ※今日はこういった 文学的 な話はしません
6. 6 「美しい文章」とは何でしょう？ エンジニアにとって
7. 7 「美しい文章」とは何でしょう？ 技術書を書くエンジニアにとって
8. 8 「美しい文章」とは何でしょう？ 技術書を書くエンジニアにとって、 初学者に技術を伝達するために必要になる
9. 9 誰もがわかりやすく読みやすい文章 論理的で説得力のある文章 1 2
10. 10 Clear 明確に伝わる Correct 内容も文法も正確である Concise 簡潔に書かれている テクニカルライティングの3C
11. 11 「美しい文章」を書けるようになろう
12. 12 主軸を作る
13. 13 When いつ Where どこで Who だれが What なにを Why なぜ How どのように 5W1H
14. 14 読むのは誰ですか
15. 15 何歳くらいの人だろう？ 男性？女性？ どんなスキルをもった人だろう？ いつ（この文章を）読むだろう？ どんな時に（この文章を）読むだろう？ どこで（この文章を）読むだろう？ なんで（この文章を）読むだろう？ 文章を読んだ結果どうなってもらいたい？ ペルソナを作る
16. 16 ペルソナを作る なぜ重要なのか • 相手の年齢や性別によって理解しやすいコンテキストが違う • 相手のスキルによって説明のボリュームが違う ◦ わからないだろうことは丁寧に説明する ◦ わかるだろうことは用語のみを提示する • 相手にどんなことを促したいかを考える必要がある ◦ 写経してほしいのか？ ◦ 読み解いてほしいのか？ ◦ リファレンスとして使われたいのか？ • 読解によって得られるものは何かを明確にする
17. 17 読ませたいのは何ですか
18. 18 主軸を作る 主軸とはなにか • 主軸とは「文章を通じて主張したいこと（主題）はなにか？」を1つ決めること ◦ 2つ以上の主軸を持たせてはならない ◦ 主軸がブレてはならない • 主軸は「結論として簡潔にあらわせる形」で提示すること ◦ 主軸をあいまいにしない ◦ 主軸を難解にしない
19. 19 主軸を作る 主軸をどう作るか • 5W1Hのフレームワークを活用しよう • 概要を書こう • 前提条件や背景を考えよう • ゴールをイメージしよう
20. 20 キーワード ElasticSearch, 全文検索 主題 ElasticSearchを用いた、全文検索エンジンの構築手順を紹介する 前提条件 （誰に？） • ElasticSearchを使ったことがない若手エンジニア • 商品DBは構築したことがあるが、全文検索の導入実績がない • 類似製品を比較検討したことがない 背景 （何で？） • 全文検索エンジンは高速であり、その素晴らしさを伝えたい • 設計や構築手順が独特であり難しい ゴール • ElasticSearchを使った全文検索エンジンを自身で構築できるようになる • 事例を通じて組み込むべき箇所を想像でき、読了後に実践する 主軸のサンプル
21. 21 文章を構成する
22. 22 文章において「最も意識」すべき単位は？
23. 23 文 Sentence 句点「。」で区切られる一文であり、文章の最小単位。 段落 Paragraph 長い文章の中の、一つの主題をもってまとまった部分。 文章 Article 長い文章の全体を指す。
24. 24 文 Sentence 句点「。」で区切られる一文であり、文章の最小単位。 段落 Paragraph 長い文章の中の、一つの主題をもってまとまった部分。 文章 Article 長い文章の全体を指す。
25. 25 段落 Paragraph 段落 Paragraph 段落 Paragraph … 文章 Article 文脈 Context
26. 26 パラグラフライティング パラグラフライティングとは • 1つの話題について書かれた段落（パラグラフ）を複数組み合わせて論理展開する文章技法。 • 日本では知名度が低いが、米国では一般的な考え方。 • パラグラフ単位で書き進める。 ◦ 主題・主張を述べる ◦ 主題・主張の補足や例示をする ◦ まとめ（結論）を述べる
27. 27 パラグラフライティング パラグラフのルール • 各パラグラフの話題は1つにする • 話題の要約をパラグラフの先頭に配置する（トピックセンテンス） ◦ トピックセンテンスだけであらすじが理解できる • 各パラグラフ内には話題の補足文のみを配置する • 文の接続詞を適切に配置する パラグラフライティングの作法-書き手にもメリットのある文配置ルール
28. 28 論理的推論法 文章構成法
29. 29 論理的推論法 代表的な論理的推論法 1. 帰納法（induction） 2. 演繹法（deduction） 3. アブダクション（abduction/retroduction）
30. 30 論理的推論法 帰納法 induction • 複数の事象をもとに1つの結論を導き出す。 • 経験論的な思考から認知する。 • フランシス・ベーコン（イギリスの哲学者）が提唱。 • 「規則」を規定することを意味する。 ◦ 「前提条件」の次に起こる「結論」の諸事例の一部から「規則」を学ぶ。 • 結論に導くための材料（事象）を多く集めるほど説得力が増す。
31. 31 イタリアンサラミはおいしい トマトはおいしい オリーブはおいしい 焼きたての生地はおいしい だから、ピザはおいしい
32. 32 論理的推論法 演繹法 deduction • 一般的な前提条件から、より個別の結論を導き出す。 • 人間の持つ普遍的な理性を原点として認知する。 • ルネ・デカルト（フランスの哲学者）が提唱した。 • 「結論」を規定することを意味する。 ◦ 「規則」と「前提条件」を用いて「結論」を導く。 • 代表的な手法として 三段論法 がある。
33. 33 論理的推論法 三段論法 syllogism 三段論法では、以下の三文を基本として論述する。 1. 大前提 誰もが当たり前に認識している事実を記載する。 例）「全ての人間は死すべきものである。」 2. 小前提 当事者でないと知らない事実を記載する。 例）「ソクラテスは人間である。」 3. 結論 これらの前提条件から結論を導出する。 例）「ゆえにソクラテスは死すべきものである。」
34. 34 人類は皆ピザが好きだ 私は人間だ だから、私はピザが好きだ
35. 35 論理的推論法 アブダクション abduction • 結果から原因を推測（仮説形成）し、観測事実に対して説明を導き出す。 • チャールズ・パース（アメリカの哲学者）が提唱した。 ◦ アリストテレスの論理学をもとにして作成されている。 • 過去事象についての「前提条件」を推定することを意味する。 ◦ 「ある前提条件が結論を説明することができるだろう」ということを裏づける。 • 何よりも想像力が重要になる。
36. 36 こぼれんばかりのチーズに注目せよ チーズは私の舌を裏切らない きっと、このピザは美味い
37. 37 前提条件 規則 結論 論理的に結論を導き出すことが重要 論理的推論法
38. 38 論理的推論法 まとめ • 事実と意見の違いを意識する。 ◦ 事実と意見を明確にわける。 ◦ 意見がどのような事実から支えられているか意識する。 ◦ 伝わり手にとって 結論の検証 を容易にする。 • MECEを意識する。 ◦ MECEに基づいて事実や意見を細分化する。（※ロジックツリー等を使う） ◦ 各項目を細分化することにより、問題の本質や解決策を絞り込める。 ◦ 意見が導き出される過程を明らかにする。 • 結論の正確性を担保し、論理が飛躍しないことを意識する。
39. 39 論理的推論法 文章構成法
40. 40 文章構成法 代表的な文章構成法 1. PREP法 2. SDS法 3. DESC法
41. 41 文章構成法 PREP法 • 構成方法は以下の通り。 ◦ Point（要点） … 要点を簡潔に伝える ◦ Reason（理由） … 要点に対する理由を説明する ◦ Example（具体例） … 理由に対する具体例を挙げる ◦ Point（要点） … 要点を再度言葉をかえてまとめる • 要点の他に説明と例をまじえる事でより理解が深まる。 • 教本やセミナーなどの教育的表現において特に有効。
42. 42 文章構成法 PREP法 Point 私は、温泉が大好きです Reason お風呂は癒しを与えてくれるからです Example 露天風呂に浸かりながら星空を眺め、木々のざわめきを感じる時間は日常を忘れ る事ができ、至福のひとときを与えてくれます Point 私は、温泉で癒やされる事が大好きです
43. 43 文章構成法 SDS法 • 構成方法は以下の通り。 ◦ Summary（要約）… 要約を簡潔に伝える ◦ Detail（詳細） … 要約についてより詳しく伝える ◦ Summary（要約）… 要約を再度言葉をかえて伝える • 日記や報告など、用途を選ばず汎用的に使える。
44. 44 文章構成法 SDS法 Summary 温泉宿は3つの癒しがあります Detail おいしい料理による味覚への癒し、温泉による肉体への癒し、そして非日常な空 間による視覚的な癒しです Summary これら3つの癒しはあなたを元気にします
45. 45 文章構成法 DESC法 • 構成方法は以下の通り。 ◦ Describe（描写） … 状況を客観的に描写する ◦ Express（表現） … 主観的な意見や問題点を表現する ◦ Suggest（提案） … 解決法を提案する ◦ Consequence（結論） … 提案によりどのような結果になるかを結論づける • 人に何かを承認させたい時に使う。 • 問題点を提起してから解決法を伝える事でより提案力が増す。
46. 46 文章構成法 DESC法 Describe 日本酒の出荷量は年々減少しています Express 今後の人口減少や高齢化の加速により更に出荷量の減少が予測されます Suggest そこで若い世代に日本酒を流行させる為の新サービス開発を提案します Consequence これにより需要を底上げし、酒蔵の廃業を阻止する事ができます
47. 47 文章構成法 まとめ • 文章構成フレームワークを覚えると構成が楽になる。 • テンプレートを作って穴埋めして文章を構成していくのがおすすめ。 • 起承転結は技術的な文章にはオススメしない。 ◦ 途中で内容が変わる「転」があると論理的な説明が難しくなる。
48. 48 主張 私は（＿＿＿＿＿＿）の（＿＿＿＿＿＿）について（＿＿＿＿＿）と考えます。 根拠 なぜなら（＿＿＿＿＿＿）だからです。 定説 一般に（＿＿＿＿＿＿）とされています。 権威付け （＿＿＿＿＿＿）によれば（＿＿＿＿＿＿）とされています。 具体例 たとえば（＿＿＿＿＿＿）です。 事例 かつて（＿＿＿＿＿＿）ということがありました。 比喩 まるで（＿＿＿＿＿＿）のようなものです。 疑問 たしかに（＿＿＿＿＿＿）という面はあります。 疑問への反論 しかし（＿＿＿＿＿＿）ではないでしょうか。 主張の繰返し それゆえ（＿＿＿＿＿＿）すべきなのです。 イシハラ式ラクラク作文シート | © 読書猿Classic （文章テンプレート例）
49. 49 テクニックとヒント
50. 50 テクニックとヒント 助詞「てにをは」に注意する 助詞「てにをは」によって文章の強弱印象が大きく変わるため、十分に注意する。 例）「そうめんでいい／そうめんがいい」 例）「オムライスは好き／オムライスが好き」 例）「母に頼る／母を頼る」 例）「東京に行く／東京へ行く」
51. 51 テクニックとヒント 接続詞「が」に注意する 接続詞「が」には逆接と順接が存在するが、使い方としては逆接が正しい。 • 逆接 … 内容が逆の文章を繋ぐ • 順接 … 内容が同じ文章を繋ぐ 例1）「今日は晴れですが、明日は雨でしょう」 例2）「今日は晴れですが、明日も晴れでしょう」
52. 52 テクニックとヒント 係助詞「も」に注意する 係助詞「も」は並列要素を接続するため、一方を省略しないよう注意する。 例1）「今日の懇親会では、ビールも出る」 例2）「今日の懇親会では、ビールもチューハイも出る」
53. 53 テクニックとヒント 格助詞「の」に注意する 格助詞「の」は様々な働きがあるため、対象が不明にならないよう注意する。 例）「ここに、父の手紙がある」 • 父宛の手紙？ • 父が書いた手紙？
54. 54 テクニックとヒント 否定表現に注意する 否定表現をできる限り肯定表現に変更することで、読みやすくなる。 例）「Go言語はJava言語のように遅くはない」 　→「Go言語はJava言語よりも高速だ」 また、二重否定表現をしてはならない。 例）「バックアップをとらなければ、万が一に備えられない」 　→「バックアップをとっておけば、万が一に備えられる」
55. 55 テクニックとヒント 受動態と能動態を使い分ける 受動態は他人の業績や一般常識のみにすることで、筆者による主張が伝わりやすくなる。 例）「Go言語のハンズオンが実施された」 　→「私は、Go言語のハンズオンを実施した」
56. 56 テクニックとヒント 私を排除する 文章に「私は」のような人称表現をすると、言葉の力が薄れる。 例）「私は売上予測について次のように考える」 　→「売上予測について次のように考える」 　→「売上予測について次のように考えられる」
57. 57 テクニックとヒント 漢字を開く 一部の漢字をひらがなにすることで、読みやすくなる。 漢字 ひらがな 殆ど ほとんど 下さい ください 更に さらに 事 こと 物 もの 漢字 ひらがな 出来る できる 良い よい 後で あとで 丁度 ちょうど 何でも なんでも
58. 58 テクニックとヒント 主語と述語のねじれに気をつける 主語と述語が一致しない文章とならないよう、注意が必要だ。 例）「私の目標は、素晴らしいサービスを作ります」 　→「私の目標は、素晴らしいサービスを作ることです」 このような 文章のねじれ は、複雑な文章でしばしば現れる。 例）「ビタミンCが多い食品はオレンジやレモンなどの柑橘類、野菜ではキャベツやじゃがいもに多く 含まれます。」 　→「ビタミンCが多い食品はオレンジやレモンなどの柑橘類です。 　　　また野菜では、キャベツやじゃがいも等に多く含まれます。」
59. 59 テクニックとヒント 一文一義にする ひとつの文の中にはひとつの意味のみとすることで、伝わりやすい文章になる。 例）「カレーを作るには、にんじん、たまねぎ、じゃがいもを洗って食べやすい大きさに切り、鍋に 油を熱し、肉と野菜をよく炒め、水を加え、沸騰したらあくを取ります。」 　→「カレーの作り方は次の通りです。 　　　まずにんじん、たまねぎ、じゃがいもを洗います。 　　　食べやすい大きさに切ります。 　　　鍋に油を熱します。 　　　肉と野菜をよく炒めます。 　　　水を加えます。 　　　沸騰したらあくを取ります。」
60. 60 テクニックとヒント 読み違いを防ぐ 文節の区切りによって読み違いを防ぐ。 例）「妻は鼻血を流しながら逃げ出した私を追いかけた」 　→「妻は、鼻血を流しながら逃げ出した私を追いかけた」 　→「妻は鼻血を流しながら、逃げ出した私を追いかけた」
61. 61 テクニックとヒント 表記揺れや文字誤りに注意する 特に注意すべき代表例は以下のとおり。 • 漢字とひらがなの表記揺れ（例：時／とき、例えば／たとえば） • 末尾にある長音の表記揺れ（例：コンピューター／コンピュータ、ユーザー／ユーザ） ◦ 3文字以上の場合は末尾の長音をトルのが一般的 • 送りがなの表記揺れ（例：行う／行なう） • 名詞形と動詞形の送りがな（例：申し込む／申込、受け付ける／受付） • 同音異義語を正しく使う（例：計る／測る、保証／保障） • 同一接続詞を繰り返さない（例：末尾の長音の表記揺れ） • ら抜き言葉を使わない（例：見れる／見られる、食べれる／食べられる） • さ入れ言葉を使わない（例：見させていただく／見せていただく）
62. 62 テクニックとヒント 指示語を避ける 指示語（こそあど言葉）は対象物を不明瞭にするため、正確な語句の記載を心がける。 例）「ここからわかるように」 　→「図1で示したグラフからわかるように」 例）「その事象については」 　→「前項で説明した〇〇の事象については」
63. 63 テクニックとヒント 重複や重ね言葉を避ける 同じ内容の繰り返しを避けることで、簡潔な文章になる。 例）「退社時は電気を消灯してください」 　→「退社時は消灯してください」 例）「多くの利用者より、質問を多く受け取る」 　→「多くの利用者より、質問を受け取る」 例）「パスポートの携行は必ず必要である」 　→「パスポートの携行は必要である」
64. 64 テクニックとヒント 話し言葉と書き言葉に注意する 話し言葉と書き言葉の違いを理解し、原則として書き言葉を使用する。 例）「やっぱり動かない」→「やはり動かない」 例）「全然問題ない」→「まったく問題ない」 例）「いっぱい稼ぐ」→「たくさん稼ぐ」
65. 65 テクニックとヒント かっこよく書かない かっこよく書こうとするほど回りくどくなる。 特に キメ台詞 は文章の質を下げるため、できる限り避けよう。 「平易な文章」を目指すことが、わかりやすさに繋がる。
66. 66 テクニックとヒント まとめ • 接続詞や助詞など、正しい日本語 を意識しよう • あいまいな表現を避け、できるだけ 肯定形 を意識しよう • 細かな 表記揺れ に注意を払おう • 必要に応じて「用語辞書」を作っておこう • 発音しながら 読み返して みよう • 以下の記事がおすすめ ◦ 文章をパワーアップしよう ◦ 今日から使える「文章作成力」 ◦ 論文の文章を推敲するための12の方法 ◦ 上手な文章を書くための改善ポイント
67. 67 最後に
68. 68 「伝える」と「伝わる」
69. 69 「伝える」と「伝わる」 あなたが届けたい内容 あなたから届いた内容
70. 70 技術者のためのテクニカルライティング入門講座 著者：髙橋慈子 発売日：2018年11月19日 価格：2,376円 理科系の作文技術 著者：木下是雄 発売日：1981年9月22日 価格：756円 数学文章作法 基礎編 著者：結城浩 発売日：2013年4月11日 価格：1,026円
71. Build Something Amazing written by ariaki4dev
72. 72 #35a16b #ff9900 #4b4b4b #4b4b4b 美しい文章 #35a16b あいうえおあいうえおあいうえお #ff9900 あいうえおあいうえおあいうえお #4b4b4b あいうえおあいうえおあいうえお ※この資料は カラーユニバーサルデザイン に基づいて配色されています