4. 執筆した初心者向け技術文書の内容確認手順
4章では、執筆した文書を確認する手順を紹介します。
4.1. 初心者向けの技術文書の基本的な確認をする
3章で紹介した以下の点をまずは確認してみましょう。
- 文章の構造が適切
- 専門用語を極力使っていない
- 不要に長い文がない
- コーディング例は必要最低限のもので構成されている
- コーディング例は容易に実行できるよう全文が記載されている。
- コードの内容が説明されている
改めて、読み返すことで修正すべきだと感じる箇所があったら修正しましょう。そういった箇所がなければ4.2.にいきましょう。
4.2. 初心者のつもりになって読み返す
自分で文書を読み返すこと自体は、よくされている方も多いと思います（いわゆる「推敲」ということですが、この記事では「読み返す」という表現にします）。
その際に重要なのは、読む人の立場になって文書を最初から通して読んでみることです。今回の場合は、初心者になったつもりで文書を最初から通して読んでみることです。
そうすることで以下の2点を確認することができます。
- すでに確認済みである4.1の改めての確認
- 4.1で気づかなかったその他の分かりにくい箇所の確認
この意識で読み返さない場合、文章としての正しさは確認できるかもしれませんが、初心者にとって分かりやすい文章という意味で確認できていない可能性があります。初心者のつもりになって読み返しましょう！
4.3. コード例を記述する場合は実際に動作させてみる
コーディング例を載せる場合は、必ず自分が書いた最終版のコードを実行してみましょう。
この作業をしないと、コンパイルエラーで動作しないコーディング例を載せることになってしまいます。なぜこのようなことが起きるかというと、読み直しを進めるなかでコーディング例を直接修正してしまい、動かないコードに改変してしまうことがあるからです。
私自身も新しい技術を学ぶ場合に記載されている例を見ながらコーディングをすると、例が間違っているために動作しない場合に遭遇します（もちろん、自分が間違っている場合もありますが）。
しかし、これが誤植であるということが分かったときは、この文章を書いた人はこんなことも確認していないのだろうかと思ってしまいます。そうした箇所が複数あると、もう読む気がなくなってしまいます。
もちろんある程度経験がある場合、コンパイルエラーから誤植の場所が分かるようになったりしますが、読者が初心者の場合はそこまでの対応ができない場合がありますので、記述したコードは最後に実行し直してみるようにしましょう。
4.4. 実際に想定する読者に読んでもらう
最後は、やはり実際に想定する読者に読んでもらいましょう。それにより、分かりにくい場所などを教えてもらい、文章を仕上げていきます。
しかし、ここでも注意が必要です。それは「初心者として分かりにくいと思う箇所を列挙してほしい」という意図を明確に伝えておくことです。さもないと改善箇所がうまく出てこないことがあります。
あまり分かっていないと思われたくない、という気持ちを確認してもらう人に持たれてしまうと、改善箇所がまったくでないことがあるからです。特に分からない箇所はありませんでした、という回答ばかりが返ってきてしまいます。
その場合には、初心者として読む場合、分かりにくい箇所があるとするとどこか教えてね、という風にお願いすると、経験上列挙してくれることが多いです。
5. 最後に
文章で相手に何かを伝える場合には、以下の点を常に意識するようにしましょう。
- 読み手に伝える量ではなく、読み手に伝わる量が大切
今回説明した内容はいずれも「伝わる量」が多くなるための手段です。大切なのは、伝えたいことの伝わる量が多くなることです。そのためには、今回説明させていただいた内容が参考になると思います。今回お伝えした点はすべて伝わる量が増えるようになっていると思います。
以上が、私が初心者向けに特に気をつけている点です。読者の皆さんにとって読んでよかったと思える文章であったなら幸いです。
