はじめに
この記事は、これから「技術同人誌」をはじめて執筆したい方に向けて、拙いながら私の経験をもとに執筆手順をまとめました。技術ブログにも共通する点がたくさんありますので、ぜひお読みください。
執筆方法は人それぞれです。本記事の内容は、ひとつの執筆手法として捉えていただければ幸いです。私はこれまで主に技術合同誌に携わってきたため、ここでも合同誌（1人あたりおおむね1章10ページ程度を書くもの）を対象にしています。もともとは社内向けに公開するつもりで書きましたが、皆さんのご参考になるかと思い公開します。この記事には、各種ツールの使い方・レイアウト・印刷・編集者向けの知識は含まれません。
どれくらいの分量を書くの？
技術書の判型は、ほとんどがA5またはB5で作成されます。1ページあたりの文字数は、文字サイズや余白サイズ、行送り、見出しの幅などさまざまな条件によって変動しますが、一般的な技術同人だとおおよそ1,000～1,400文字程度になります。ページ数があらかじめ決められている場合、まずは最低限の目標文字数を決め、書き進めながら分量を調整するのがよいでしょう。
ご参考までに、Re:VIEWテンプレートにおける最大文字数は次のとおりです。
| 判型 | 文字サイズ | 文字数 |
|---|---|---|
| B5 | 10pt | 1,400文字（40文字×35行） |
| A5 | 9pt | 1,406文字（38文字×37行） |
どれくらいの時間がかかるの？
執筆速度は人それぞれですが、たとえば合同誌に10ページ程度（10,000〜14,000文字）の原稿をはじめて寄稿する場合、下準備を含め最低30時間程度の作業時間を見込むべきでしょう。筆が早い方だと1ページあたり1時間以内で仕上がることもありますが、時間に余裕をもつのに越したことはありません。また、事前調査・動作検証・図表作成など、必要に応じてさらに多くの準備時間を費やす可能性もあります。
執筆の後半になるほど集中が必要になります。スケジュールに余裕をもって書き進めてください。決して締切駆動にならないように、注意しましょう。
気をつけることはある？
まず、執筆をはじめる前に、技術書の多くは印刷・製本されるということを再認識してください。印刷されたものは、改版/増刷しないかぎり内容を訂正できません。誤字などのミスで後悔することのないよう、普段の文章以上に気をつけてくださいね。
また、読者は「印刷物を読む」ということを忘れないようにしましょう。たとえば数ページに渡るような長いソースコードを記載しても、すべてを写経して動かす人はほとんど居ないですよね（20年以上前にはそういった雑誌が流行ったこともありました）。ソースコードなどのデータは、GitHubに公開してリンクを掲載すると親切ですね。
Re:VIEW記法を覚えよう
今日、技術書（同人誌）の多くはRe:VIEWを使って書かれています。Markdownで書き、Re:VIEW形式に変換することもできますが、やはり直接Re:VIEW形式で書く方が格段に表現力が高く、手間もかかりません。少しクセのある特殊な記法ですが、Re:VIEWを使う際にはぜひ覚えてください。
文章を書く前に
文章を書く前に、どのようなことに気をつければよいかを簡単に予習しましょう。文章力を鍛えるには多くの経験が必要ですが、要所をおさえることで初心者でも読みやすい文章を書くことができます。たとえば、私が作成した過去の発表資料「美しい文章 - Speakerdeck」をご覧ください。
文章を書く際に気をつけること
文章において重要なポイントは次の2つです。
- 誰もがわかりやすく、読みやすい文章を書く
- 論理的で、説得力のある文章を書く
これを実現するために「テクニカルライティング」という考え方があります。内容を読み手に正しく伝える要素として次の「3つのC」に気をつけます。
- Correct（正確に書く）
- 正確な表現に注意することで、文章全体の信頼性を高めます
- 数値や単位の誤記、綴り間違えなど、ちょっとした誤りがないよう注意しましょう
- Clear（明確に書く）
- 読み手が内容を理解しやすい文章を心がけます
- 具体的な文章より、誰が読んでも同じ理解を得られる文章を目指しましょう
- Concise（簡潔に書く）
- 語数を減らし、短い文章によって、強く明確な印象を与えます
- 長い表現を避け、文中に複数の内容を詰め込まないよう注意しましょう
パラグラフライティング
「パラグラフライティング」は欧米で主流の考え方で、文章を段落（パラグラフ）単位で設計します。すべての文章がこのルールに従う必要はありませんが、読みやすいだけでなく文章構成しやすいため、効果的に使ってください。
- 段落内で扱う話題は1つに絞る
- 段落の最初で要点を述べ、そこだけを読んで理解できる状態にする
- 続く段落内には、先頭の文を補助する内容のみを記載する
- 段落の末尾で内容をまとめる
文章を段落（パラグラフ）ごとに分け、1つの話題だけを書くことで、読者が理解しやすい文章になります。また、著者にとっても、話題が分散しないため書きやすいというメリットがあります。はじめはとにかく「細かい単位に集中して書く」ことを意識してください。
執筆の流れ
本の執筆はブログなどに比べ文章量が多く、首尾一貫した内容を作り上げることは相当に難しい作業です。ここでは、私が考える「書きやすい手順」をお伝えします。
もっとも伝えたい内容を決める
はじめに立ちはだかる難関は、なんといってもテーマ決めです。ここでは「自分なんかに伝えられる技術はない」という気持ちは捨てましょう。あなたがこれまでに獲得してきた知識は、確実に他者の役に立つ有用な情報です。もし、テーマ決めで悩むようなら、「あなたの知識で他者の悩みを解決できることはないか」を考えてください。たとえば、次のような内容を自身に問いかけてみると、いくつか良いアイデアが出てくるかもしれません。
- 周囲が困っている課題のうち、あなたが解決できることは何でしょう？
- あなたが最近悩んだ技術的な課題と解決策は何でしょう？
- あなたがもっともアツく語れる技術は何でしょう？
- いまプロダクトに導入を検討している技術はありませんか？
- 最近なにか比較検証した技術はありませんか？
そして、テーマを決める際には、他者の視点をもつことも重要です。書きたい内容が浮かんできたら、周囲の方とディスカッションしてください。他者と話すことで、あなた1人では思いつかないようなアイデアが出てくる可能性があります。
あわせて、次のような内容を決めておくと、全体の流れがピシっとするのでオススメです。これらが具体的に定まるほど、文章の方向性が明確になり、楽に書き進めることができます。
- どんな人に読んでもらいたいか（ターゲット）
- 読み終わったあと読者にどうなって欲しいか（ゴール）
構成を決める
テーマが決まったからといって、いきなり最初から最後までを書き進めることはできません。読者は、まずタイトル（テーマ）をもとに本を読み進めるわけですから、内容に一貫性を持たせ、テーマから外れないよう工夫が必要です。本文を書きはじめる前に、テーマに沿った構成、すなわち「執筆の設計書（アウトライン）」を作りましょう。この段階では、見出しをつくり、あらすじをつくるまでが目標です。
見出しは、書こうとしている内容のイメージを表現するものです。頭の中にあるイメージを自身で再確認し、読者に対してわかりやすく提示していくための道標にもなります。また、見出しを細かく決めることにより、執筆を「より小さな単位」で捉えることができるようになります。1万文字を超えるような原稿を想像しながら書くことは難しいかもしれませんが、たとえば500文字であれば想像しやすいですよね。箇条書きでよいので、まずは思いつく限り見出しをたくさん書き並べます。
見出しが揃ったら、いったん並べ替えて整理しましょう。次に、見出しのなかからグループ化できるものがないかを探します。見出しを大小に分け、必要に応じて小見出しを加えて粒度を揃えます。ここまでで大小2階層の見出しを整え終わりましたね。※もっと細かく分類したくなったら、同様の手順で3階層にわけても構いません。
続いて、見出しごとにあらすじを書きます。この段階では雑な文章で構いませんので、見出し内でもっとも伝えたい内容をまとめましょう。ここまで書き終えたら「なんとなく本ぽいもの」ができているはずです。
最後に、全体を何度か読み返し、説明の流れに違和感がないかを確認してください。次のような視点でチェックするとよいでしょう。
- 伝えたいことがすべて書かれているか
- 主張は一貫しているか
- 理解しづらい部分はないか
- 抜けている観点はないか
- 説明の流れや順序は適切か
できるならこの段階で他者のレビューが入ると、より良い記事が生まれます。ここまできたら、半分以上進んだといっても過言ではありません。
それほど下準備は大切な工程です！
肉付けする
前項でつくったあらすじを元に、文章を書き進めます。
執筆には大変な集中力を要しますので、一気にすべてを書き進めないよう注意しましょう。長時間おなじものに向かい続けると脳が疲弊し、気力も失ってしまいます。パフォーマンスを持続させるためには、定期的に執筆時間をとり、見出しごとなど一定量に区切った執筆をオススメします。また、毎日同じ時間帯に同じ作業をすることで、心理的に書きやすくなります。自分なりにテンションをあげやすいゴールデンタイムをみつけ、その時間を上手に使ってください。
書く際には勢いをもってどんどん内容を拡げ、出し切ってください。「書きながら迷ったり取捨選択しない」を目指すことで、アウトプットの効率が最大化します。区切りごとに読み返し、不要な部分を削ったり、品質をあげればよいのです。
最後に、「書き始めるのはどこからでも良い」と考えておくと、詰まりにくくなります。すでに文章のアウトラインが決まっていますので、どの部分でも書き進めることができるはずです。順番に書き進めて詰まるくらいなら、もっとも書きやすい部分に手をつけて進捗させましょう！
全体を読み返す
すべての文章を書き終えたら、最低10回は全体を読み返します。書かれている技術についてまったく知らない状態として、その文章はすんなり入ってきますか？1回だけ読み返すなんてとんでもない。ここで読み返した回数が、そのまま品質に繋がります。気になった部分は、加筆修正し、並び替え、できるだけ納得できる文章に近づけましょう。
読み返す際には、できるだけ完成本と同じ状態（レイアウト）にしてください。また、電子データだけでなく、紙に印刷してみましょう。ディスプレイと紙では印象が変わり、異なる発見が得られるはずです。
校正する
文章全体が自身で納得できる状態になったら、まずは自身で校正しましょう。ここでの校正は、送りがな・揺らぎ・接続詞・誤字や誤用など、日本語として問題ないかをチェックする作業です。すべて手作業でもできますが、専門知識がないと精度を上げるのは困難でしょう。
VSCodeプラグインの「テキスト校正くん」を使うと、問題の多くを自動チェックできます。
査読を依頼する
自身での校正が終わったら、できるだけ他者に査読を依頼しましょう。ここで日本語の誤用を指摘されないよう、あらかじめ自身で充分校正してくださいね。自分とは違う観点のチェックを経ることで、文章の伝わりやすさが格段に向上します。
査読される方は、次に注意してチェックしてください。
- 技術的な誤りはないか
- 結論は納得できるか
- 全体の流れは理解しやすいか
- 見出しの並びは問題ないか
- 補足すべき（抜け落ちている）情報はないか
完成
おめでとうございます！あなたの原稿は完成しました。入稿まで時間の許す限り読み返して、少しでも気になることがあれば改善を繰り返してください。あなたの書いた素敵な本が、手にとる方へと幸せを運びますように。
最後に
「技術同人誌を書こう - アウトプットのススメ」など、技術同人誌を書くにあたって有用な書籍や情報がたくさんあります。また、執筆でわからないことを助けてくれるようなコミュニティもあります。この記事が目にとまったあなた！書くのはこわくない、技術書は楽しいぞ！みんなで書こう！