Boost」など、さまざまなカンファレンスを企画・運営しています。BOOKS(コードジン・ブックス)は、CodeZineの連載からカットアップした、開発現場の課題解決に役立つ書籍シリーズです。初心者向けの技術文書を執筆する手順3章では、初心者向けの技術文書を執筆する際に、自分が実践している手順を紹介していきます。コーディングの例を書く場合などには、特に参考にしていただけると思います。文章の構造から組み立てていくいきなり文章を書き始めるのではなく、最初に文書の章立てを考えます(この文章でいうところの3.X.の部分です)。その次に、各章で何を言いたいかを箇条書きで書いてみます(この文章だと3.X.の中身を箇条書きで書くことです)。この時点で、初心者向けの文書としての内容が適切か確認します。初心者を対象としている場合、本当に重要な内容のみを記述するようにします。初心者にとって不必要な情報が多くなると、どの箇所が重要な情報かが分からなくなり、本当に伝わりにくくなってしまうからです。次に初心者向けの文書いう点で、ボリュームがあり過ぎないかなどを一度考えます。ボリュームが多すぎる場合には、章の構成や箇条書きの量を調整します。このようにして全体の構成や伝えたい内容が決まった後、実際に文章を書いていきます。専門用語は極力使わない専門用語を使う際には非常に気を使わなくてはいけません。専門用語が一番最初にでてくるときにその説明を記述するのは、文章を書くお作法として基本的なことなのでご存知の方も多いと思います。想定している読者が今回の執筆入門のように初心者の場合には、重要なポイントがまだあります。それは、説明が必要な専門用語自体をあまり使わないことです。専門用語がどれだけあっても説明がついていれば正しい文章ではありますが、消化不良になってしまうため伝わりにくい文章になる可能性があります。専門用語を使わないような内容にしましょう。しても使わないといけないとしても、一般的な表現などで表現できるのであればそうするようにしましょう。例)新入社員向けのJavaの記事にて新入社員向けのJavaの記事を執筆するにあたって、コーディングするクラスについての関係図であるクラス図があった方が分かりやすいと思い記載することにしました。読み返している内に、ここで本当に伝えたいのは何かと改めて考えました。考えると本当に伝えたいのはクラスの関係であったため、クラス図を使わず簡略したクラス図のような図を記載することにしました。このように専門用語を使って説明してもよいのですが、使わなくてもいいのであれば極力専門用語は使わない方がよいです。初心者に負担がかからないようにすることが大事です。長い文は短く、コーディングの例は全部をシンプルに長い文は短く全体的な構造や用語に気をつけて、文章をある程度書けたとします。その次に気をつけるべきことは、文そのものをなるべく短くすることです。文は長くなればなるほど理解に時間がかかってしまいますので、長い文がある場合は文を分けて短い文にしていきましょう。コーディングの例は全部をシンプルに技術文章ならコーディングの例を記述する場合があると思います。初心者向けとしては、コーディングの例は実行可能な全部のコードが記載されていることが望ましいです。部分的な例の場合、初心者は実行させることができないかもしれないからです。そのときにはコーディングの内容がシンプルであることが重要になります。不要に多い変数や必要のない関数が定義されているコーディングの例だとあまりに長いコーディングになりそれだけで読む気がなくなります。これは文章を書いている人が過去の自分のコーディングなどを少し修正するだけでほぼそのまま記載している場合、このようなことがおきます。読者がある程度経験があると、必要な箇所と不要な箇所の判別ができるので、必要な箇所のみ参考にすることができ、あまり問題にならないかもしれません。初心者の場合、そういった不要な箇所の判別ができないため、結局書いてあるままコーディングするしかない場合があるからです。初心者にとって分かりやすくするために、コーディングの例は実行可能な全コードをシンプルに記述するようにしましょう。コーディングの説明はしっかりコーディングの例を実行可能なコード全体としてシンプルを記述した後は、しっかりそのコーディングの内容を文章で説明するようにしましょう。コーディングのそれぞれの箇所で、どういった意味があるのかをしっかり説明して、説明不足にならないように気をつけます。初心者が読んでも理解できるように、基本的にすべてのコードを説明するようにします。実際にコーディングして実行可能であっても、それらのコードの内容を理解してこそ意味があるからです。裏を返せば、読者が理解できないコードを見せて、それを無事実行できたとしても、それではほとんど意味がないからです。例)新入社員向けのJavaの記事にて前述したJavaの記事ですが、この記事は基本的にすべてのコードに対して説明するようにしました。1行ずつ説明する箇所もあれば、数行をまとめてこのような意味になっているという箇所があったりしました。再度同じコードが記述されているような場所では説明を省略しました。読者にとって、意味が分かるようにしっかり説明できていれば、それでよいと思います。エイジ)外資系大手IT企業にて、大型SI案件のメンバーとしてプロジェクトに参画。現在では、SI案件の見積りツールの展開を担当している。NEW1DMM.comの施策から見る、事業をむしばむ「技術負債」への処方箋──リファクタリングの「言語化」でインシデントを予防2企業の7割超が「2025年の崖」を理解していないことが明らかに。NEW1DMM.comの施策から見る、事業をむしばむ「技術負債」への処方箋──リファクタリングの「言語化」でインシデントを予防2企業の7割超が「2025年の崖」を理解していないことが明らかに。NEW1DMM.comの施策から見る、事業をむしばむ「技術負債」への処方箋──リファクタリングの「言語化」でインシデントを予防2企業の7割超が「2025年の崖」を理解していないことが明らかに。12:00法務担当者、6割超が今後業務で「生成AIを使用したい」と回答。NEW新着記事一覧を見るイベント今後の予定を見るCodeZineは、株式会社翔泳社が運営するソフトウェア開発者向けのWebメディアです。「デベロッパーの成長と課題解決に貢献するメディア」をコンセプトに、現場で役立つ最新情報を日々お届けします。イラストの無断転載を禁じます。記載されているロゴ、システム名、製品名は各社及び商標権者の登録商標あるいは商標です。