解説をとばす

技術系の記事の場合、どうしても「例外」があったり、ケースによって必要なことが異なることがあります。これらを一文の中で説明しようとすると、どんどん結論が先延ばしされて、全体的に難解な文章になっていってしまいます。

そこで、文章ではそのような例外などをどんどんとばして簡潔に説明し、代わりにコラムなどを使って、一つずつ紹介をします。

例）
6-23の手順に従って、データベースも新しいサーバーに復元していきます。この時、
サイトのドメインが変わる場合には復元する前にコラムの手順を行いましょう。
（WordPressをちゃんと理解するための教科書 p299）

英語の用語は日本語訳する

特にプログラミングの世界などでは、英語がそのまま用語になっている場合があります。例えば「オブジェクト」や「メソッド」「パラメーター」など。

WordPressでも「フック」や「フィルター」などがあります。これらの言葉、実際にはなんと言うこともない言葉でも、初心者の方にとっては「知らない言葉がまた出てきた」と身構える要因になります。

そこで、これらは「用語」として解説せずに、日本語訳をしてしまいます。

例）
フック（hook）とは英語の「留め金」の意味の単語で、WordPressはさまざまな処理を行うとき…
（WordPressをちゃんと理解するための教科書 p208）

「フック」という言葉をそのまま使わず、「留め金」ですと解説することで、その後の解説を読み進める中で「あ、留め金の役割をしてる！」とイメージしてもらいやすくなるのではないかと思います。

初心者にとっては、見るものすべてが新鮮で、なにが大切でなにが大切でないかの判断がつきません。

例えば、プログラミングの世界ではよく「とりあえず使う変数名」として「hoge」とか「fuga」という変数名を使います。これには意味はありません。

また、繰り返しの処理の変数には「i」というのがよく使われ、さらに続けて「j,k」と使うことが多いです。これらも初心者にとっては「iってなに？　fugaってどういう意味？」という疑問が湧きます。

そこで、「よくわかるPHPの教科書」では「$iの謎（p65）」というコラムで、その謎を紹介しました。実際には、私自身も$iがなぜ使われるのか、確証はありません。それでも、初心者にとっては放置されないことが大切かなと思います。

プログラミングの世界では、専門用語ではないが、なんとなく使っている「業界用語」のようなものが多々あります。

例えば、プログラムの解説ではよく「返す」という言葉を使います。「dateファンクションが値を返す」といった使い方。

この「返す」という言葉は意味が曖昧です。ここでは「返却する」の意味で使われているのですが、読んでいる方は「ひっくり返す」のか「元に戻す」のかなど、いろいろな意味を勘ぐってしまいます。

そこで、このような業界用語は極力使わずに、「読者がどうなるのか」を基準にして言い換えます。ここでは、次のように言い換えました。

例）
これをパラメーターに指定すると現在の時が得られるわけです。
（WordPressをちゃんと理解するための教科書 p172）

「得る」という言葉に言い換えました。ファンクションが値を返すということは、読者はその値を「得る」事ができるわけで、この方が分かりやすいかなと考えます。

プログラミングの解説には、専門用語を利用するのが欠かせません。
しかし、初心者の方には多くの専門用語を一気に覚えなければならず、数ページ後には前に出てきた用語を忘れてしまいます。

そこで、2度目以降に出てきたものについては、必ずどこで解説したかを示すようにしています。

例）
「今日の日付」を取得するのは、Lecture5-1で紹介した「date」ファンクションを用いることができます。
（ちゃんとWordPressを理解するための教科書 p191）

こうして、忘れてしまった方がすぐに戻れるように工夫しています。（ただ、実はこのLecture番号を記載するのは、編集者さんにお願いしていることなので、面倒な作業をお願いして恐縮です。ありがとうございます。）

以上、いくつか代表的なものをご紹介しました。こんな感じで、一文一文に気を遣いながら、文章を綴って入門書を書いています。
1人でも多くの方に、プログラミングの楽しさを味わっていただければなと思います。

ということで、次は日高彰 – Adventar さんです！（途中に空いている日もあるので、ご興味ある方はぜひ！）