3. 初心者向けの技術文書を執筆する手順
3章では、初心者向けの技術文書を執筆する際に、自分が実践している手順を紹介していきます。コーディングの例を書く場合などには、特に参考にしていただけると思います。
3.1. 文章の構造から組み立てていく
いきなり文章を書き始めるのではなく、最初に文書の章立てを考えます（この文章でいうところの3.X.の部分です）。
その次に、各章で何を言いたいかを箇条書きで書いてみます（この文章だと3.X.の中身を箇条書きで書くことです）。この時点で、初心者向けの文書としての内容が適切か確認します。初心者を対象としている場合、本当に重要な内容のみを記述するようにします。初心者にとって不必要な情報が多くなると、どの箇所が重要な情報かが分からなくなり、本当に伝わりにくくなってしまうからです。
次に初心者向けの文書いう点で、ボリュームがあり過ぎないかなどを一度考えます。ボリュームが多すぎる場合には、章の構成や箇条書きの量を調整します。
このようにして全体の構成や伝えたい内容が決まった後、実際に文章を書いていきます。
3.2. 専門用語は極力使わない
専門用語を使う際には非常に気を使わなくてはいけません。専門用語が一番最初にでてくるときにその説明を記述するのは、文章を書くお作法として基本的なことなのでご存知の方も多いと思います。
しかし、想定している読者が今回の執筆入門のように初心者の場合には、重要なポイントがまだあります。それは、説明が必要な専門用語自体をあまり使わないことです。専門用語がどれだけあっても説明がついていれば正しい文章ではありますが、消化不良になってしまうため伝わりにくい文章になる可能性があります。極力専門用語を使わないような内容にしましょう。
もし、どうしても使わないといけないとしても、一般的な表現などで表現できるのであればそうするようにしましょう。
新入社員向けのJavaの記事を執筆するにあたって、コーディングするクラスについての関係図であるクラス図があった方が分かりやすいと思い記載することにしました。
しかし、読み返している内に、ここで本当に伝えたいのは何かと改めて考えました。そう考えると本当に伝えたいのはクラスの関係であったため、クラス図を使わず簡略したクラス図のような図を記載することにしました。このように専門用語を使って説明してもよいのですが、使わなくてもいいのであれば極力専門用語は使わない方がよいです。なるべく初心者に負担がかからないようにすることが大事です。
3.3. 長い文は短く、コーディングの例は全部をシンプルに
長い文は短く
全体的な構造や用語に気をつけて、文章をある程度書けたとします。その次に気をつけるべきことは、文そのものをなるべく短くすることです。文は長くなればなるほど理解に時間がかかってしまいますので、長い文がある場合は文を分けて短い文にしていきましょう。
コーディングの例は全部をシンプルに
技術文章ならコーディングの例を記述する場合があると思います。初心者向けとしては、コーディングの例は実行可能な全部のコードが記載されていることが望ましいです。部分的な例の場合、初心者は実行させることができないかもしれないからです。
ただ、そのときにはコーディングの内容がシンプルであることが重要になります。例えば、不要に多い変数や必要のない関数が定義されているコーディングの例だとあまりに長いコーディングになりそれだけで読む気がなくなります。
これは文章を書いている人が過去の自分のコーディングなどを少し修正するだけでほぼそのまま記載している場合、このようなことがおきます。読者がある程度経験があると、必要な箇所と不要な箇所の判別ができるので、必要な箇所のみ参考にすることができ、あまり問題にならないかもしれません。しかし、初心者の場合、そういった不要な箇所の判別ができないため、結局書いてあるままコーディングするしかない場合があるからです。
初心者にとって分かりやすくするために、コーディングの例は実行可能な全コードをシンプルに記述するようにしましょう。
3.4. コーディングの説明はしっかり
コーディングの例を実行可能なコード全体としてシンプルを記述した後は、しっかりそのコーディングの内容を文章で説明するようにしましょう。コーディングのそれぞれの箇所で、どういった意味があるのかをしっかり説明して、説明不足にならないように気をつけます。
初心者が読んでも理解できるように、基本的にすべてのコードを説明するようにします。実際にコーディングして実行可能であっても、それらのコードの内容を理解してこそ意味があるからです。裏を返せば、読者が理解できないコードを見せて、それを無事実行できたとしても、それではほとんど意味がないからです。
前述したJavaの記事ですが、この記事は基本的にすべてのコードに対して説明するようにしました。ただし、1行ずつ説明する箇所もあれば、数行をまとめてこのような意味になっているという箇所があったりしました。再度同じコードが記述されているような場所では説明を省略しました。読者にとって、意味が分かるようにしっかり説明できていれば、それでよいと思います。
