目次
記事の目的
自分は先日、こちらのブログを書きました。
【感想】『技術者のためのテクニカルライティング入門講座』――実務で使う文章に指針を与えてくれる本 - LEFログ：学習記録ノート
この書籍では、業務におけるライティング技術について書かれていました。
今回は、論文やレポート、数式やコードの説明を書く際の作法について述べられている、結城浩さんの『数学文章作法 基礎編』を取り上げたいと思います。
第１章 読者
文章を書くときは「読者のことを考える」必要があります。
そのためには、読者の知識・読者の意欲・読者の目的の３つを意識する必要があるとのことです。
このブログ記事の場合だと、次のようになるでしょう。
- 読者の知識：不特定多数が閲覧するため、前提知識がなくても読めるようにする
- 読者の意欲：おそらくネットサーフィンのついでに読まれるはず。記事が長すぎると読まれない。
- 読者の目的：
- 『数学文章作法 基礎編』の内容を知りたい
- このブログ主（LEF）の感想を知りたい
第２章 基本
この章では、形式と主張について述べられていました。
以下に、自分が感銘を受けたポイントを書いていきます。
漢字とかなに気をつける
自分は京極夏彦さんの小説が好きで、ついつい漢字をたくさん使ってしまいます。
しかし、論文やレポートでは控えるべきです。
特に自分が無意識に使っていたのは、「～する時、〇〇」という表現でした。これは「～とき、〇〇」のように、漢字からひらがなに変える必要があるそうです。
一つの文で一つの主張を行う
自分なりに悪い例を考えてみました。
「私はリンゴが好きですが、バナナも好きです」
この文章だけで、２つの改善点があります。
- 逆説でない「が」を削除できる。
- 一つの文で一つの主張をする。
改善すると次のようになります。
「私はリンゴが好きです。同様にバナナも好きです。」
この例の場合は、文が短いのであまり効果が分かりづらいですが、より複雑な文では効力を発揮します。
接続詞を使う
これは先日の『技術者のためのテクニカルライティング入門講座』とは異なる部分です。
分かりやすく、そして読みやすい文章を達成するためなら、接続詞を使ってしまって良いそうです。文の関係を明らかにすることを目的にしています。1
文末に変化をつけて読みやすくすることもできます。
もちろん、接続詞の使い過ぎは良くないと思います。しかし、対外的でフォーマルな文章と違って、あまり堅苦しくする必要はないと分かりました。
第３章 順序と階層
驚き最小の原則
「驚き、最小の法則」というのは、 仕事を円滑に（人間関係を円滑に）進めるには「相手の驚き」を最小にすることが大切だ、 という法則です。
このことは、文章を書くうえでも大切ということが述べられています。
具体的には、これらを意識する必要があります。
- 時系列順
- 作業順
- 位置順
- 大きさ順
また、驚きを小さくするために、次の順序も大切になってくるとのことです。
- 既知 → 未知
- 具体 → 抽象
- 定義 → 使用
表現の工夫方法
表現の工夫には、箇条書きや書体（フォント）、字下げやパラレリズムといった方法があることが分かりました。
特に自分が気をつけようと思ったのは、文の途中に列挙を挟まないことです。
そしてこれは、コードブロックに関しても当てはめることができると思います。
［ダメな例］
RubyではHello World!を出力する際、
puts "Hello World!"
と書きます。
［OKな例］
RubyではHello World!を出力する際、次のように書きます。
puts "Hello World!"
書籍には、このように書いてありました。
（……）一文がとても長くなってしまうため、読んでいて息が苦しくなります。(p.76)
つまり、文の途中に別の要素を挟むのは、なるべく避けたほうが良いということです。
もちろん、途中に挟まる要素が短い場合には、一文の中に入れてしまっても良いかもしれません。
しかし、コードブロックが長くなってしまうような場合は、事前に文を閉じたほうが読みやすくなることが分かりました。
第４章 数式と命題
この章では、読者を混乱させないことと、メタ情報を与えることについて書かれていました。
正直ちょっと難しかったのですが、自分なりにプログラミングでも応用できるところをピックアップしてみます。
用語の定義をきっちりする
『アジャイルプラクティス』でも同じようなことが述べられていた気がしますが、プロジェクト内において、「同じ概念に異なる用語を使っている」「異なる概念に同じ用語を使っている」と、混乱を引き起こす原因になります。
そのためプロジェクトの開始時に、リポジトリの近くにWikiを設けておいて、そこに用語の定義を書いておくと、コミュニケーションを潤滑にすることができます。
例えばアジャイル開発だと「スプリント」と「インクリメント」という用語があります。この違いを説明するのは難しいです。
しかし、あらかじめそのプロジェクトにおいて「スプリント」と「インクリメント」の定義についてしっかり書いておけば、スクラムマスターや開発者は迷わずにプロジェクトを進めることができるでしょう。2
メタ情報を使う
メタ情報とは、読者に理解の手がかりを与える情報のことです。
自分が連想したのは、レビュー時のConversationです。
例えば自分がPull Requestを出して、相手の方が質問したとします。その際、ただ単に質問に答えるだけではなく、根拠となる出典（公式ドキュメント等）へのリンクを貼れば、説得力は増します。
変数名やメソッド名、型情報に注意することも、相手にコードを読んでもらうためのメタ情報になり得ると思います。
コード内コメント、Gitのコミットメッセージ、そしてGitHubでのコメントもメタ情報として有効です。
第５章 例
例示は理解の試金石
自分は自作サービスにおいて、Reactを使いました。
チーム開発に取り組むまで、Reactは一切触ったことがありませんでした。Vue 2（Options API）を辛うじて理解できる程度で、「リアクト？なんか難しそうぢゃん」というイメージしかありませんでした。
しかし、チーム開発で、実際に動いているReactのコードに触れる機会がたくさんありました。そこで自分は具体例にたくさん触れることができたのです。
これは自分にとって大きな学びになりました。それまでは公式ドキュメントを読んでもうまくイメージできなかったReactを、確かな実感を持って理解し、使えるようになったのです。
フロントエンドは苦手なので、まだまだレベルは低いですが、「何も分からない」→「ちょっとわかった！」の足掛かりになったのは、具体的なコードに触れたからこそです。
『数学文章作法 基礎編』の中で、次のように書かれています。
「良い例を作れるくらい、自分はこの概念を理解しているだろうか」と自問しましょう。
これは、「良いコードを書けるくらい、自分はこの概念を理解しているだろうか」と置き換えることができると思います。
第６章 問いと答え
この章をまとめると、次に集約されます。
――相手に問いかけたら、答えもきちんと明示しよう。
少し話が逸れてしまいますが、「学校」という場所に通っていた頃、苦手な先生がいました。
その先生は問題を出したあと、いつまで経っても答えを教えてくれないのです。「自分で答えを考えることに意義がある」とのことでした。質問すると、その先生は機嫌が悪くなるため、質問したくても出来ないクラスメイトが何人もいました。
でも、よく考えてみてください。自分は「生徒」であり、その問題の解決方法を知りません。だから、「先生」が提示する解答を期待しているのです。もし解答が提示されないのであれば、自己流の解決方法を編み出すしかありません。その自己流が、問題解決のための最適解であることは少ないです。足し算しか知らない生徒は、掛け算を知ることで成長します。
もちろん自分で考えることは大切です。しかし、模範解答がないと、本当に成長できたかのメルクマールを確認できないのです。
昔話をしてしまいましたが、この思い出を反面教師にして、自分は積極的に「答え」を教えてあげられるような大人になりたいと思ったのでした。
第７章 目次と索引
今回、このブログでは珍しく目次を入れてみました。
また、脚注も入れてみました。
今まで食わず嫌い（？）でやっていなかったのですが、試しにやってみると、Markdown形式でも簡単に導入できることが分かりました。これからは読みやすさのために、長い記事では積極的に使っていきたいと思います。
第８章 たったひとつの伝えたいこと
まとめ：読者のことを考える
《読者のことを考える》
これが、書籍を通じた一貫したテーマでした。
そしてそれは、先日取り上げた『技術者のためのテクニカルライティング入門講座』とも通じるところがあります。
なぜ人が文章を書くのかというと、それは読んでもらうためです。たとえ読み手が自分一人しかいないとしても、将来の自分が読みやすい文章を書くべきです。
読んでもらえない文章には意味はありません……とは思いません。ただ、自分の経験上、「読まれない文章を書くことは本当に苦しいです」とお伝えしておきます。
どんなに内容が素晴らしくても、読まれなければ評価をされるのは難しいです。
だから、少しでも読まれる努力をするために、これからも工夫をしていこうと思いました。
次回
『数学文章作法 推敲編』に続く
