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