探検！編集、執筆工場〜某媒体の記事ができるまで

明けましてメリークリスマス！　2013年の12月がやってまいりました。

CodeGridの記事ができるまで

Editors' & Writers' Advent Calendar 2013の第1日目です。

第2日目は、えどさんの記事を書くときに気をつけていることです。

この記事では「探検！編集、執筆工場〜某媒体の記事ができるまで」と題しまして、CodeGridというフロントエンドまわりの技術情報を配信するサービス（有料）の記事ができあがるまでをご紹介したいと思います。

対象としては、技術者でちょっとなにか記事を書いたりしたいんだよね、という方や、技術書の編集に関わる方を想定しています。エンジニアではないフツーの編集者のワークフローなので、そこまで複雑なことはしていません。

技術情報系の記事の特徴

技術情報記事といいますと、まず情報自体に間違いがあってはいけません。そのため執筆者（いい感じの最強エンジニア）が記事を書いた後に、以下のような過程を経て、読者の手元に届くことになっています。

* 文章構成の妥当性を考える。
* 社内で技術的なレビューを行う。
* 日本語として理解しやすい、読みやすい文章にする。

つまり、ひとつの記事をめぐって複数人で校閲（主に技術面）、構成（主に文章面）を行うわけです。こんなときに便利なのが、バージョン管理や共有が簡単にできるGitとGitHubです。

Gitとはバージョン管理と、複数人でのソースの共有（しようと思えば）できます。主に、技術系の開発現場で使われているシステムです。

ですが、なにも、Gitはコードを書く人だけのためのものではなく、原稿執筆しちゃうぞ！編集しちゃうぞ！という方にも非常に便利に使えます。

誰が文章のどのあたりをいつ直したか、その履歴も残りますし、やっぱり前の方がいいよね（ま、実際にはめったに起きないことですが……）、ということが起きても、大丈夫なわけです。

原稿をお届けするまで

んでは、実際のフローをご紹介します。

1. 執筆者は原稿を書く

だいたい誰がどんなテーマで記事を書くかは、向こう一ヶ月くらい決まっています。執筆者は自分の順番が来たら、おもむろに記事を書きます。このときの形式はMarkdownで書きます。

2. 原稿ができたら校正用のリポジトリにpush

原稿ができたら、GitHub上にあるプライベートリポジトリにpushします。

するってえと、社内チャット（CampfireをPropaneというアプリを使って見てます）にも、pushしたログが出力されます。次のような感じで。

ここで編集者は「お。原稿あがりましたね」ということに気づくわけです。

追記：2013.12.7

このチャットシステムとの連携は、各リポジトリのSettings > Service Hooksで設定できます。海外のチャットシステムの主なものは、ぼほカバーされています。カバーされていない日本のチャットサービスは、APIが公開されていれば、がんばればできるかもしれない（私にそのスキルはないです、笑）！

3. 執筆者がissueを立てて、編集者にパス

執筆者は原稿を書いたことをissueを立てて、編集者に知らせます。なにか申し送り事項があれば、ついでにつらつらと書いたりもします。

編集者は、発行日ごとにMilestoneを切っておいて、そこにissueをぶら下げていきます。

4. がんばって編集

編集者はリポジトリから原稿やら付属の図版、デモファイルなどをGitでpullします。ちなみに執筆陣はエンジニアなので、ほぼCUIで、編集者はSourceTreeというGUIツールを使っています。

編集者はもらったMarkdown形式のファイルを自動的にjade形式に変換します。このあたりのすてきシステムは、フロントエンドエンジニアの@hokacchaが作ってくれました。

で、そのファイルをせっせと編集します。

- わかりにくい表現はないか

技術的に難しいものを難しい日本語で書いたら、二重苦ですからね。

- 実際に自分のマシンに環境を作って試してみる

編集者の環境は普段開発をしていないので、わりとクリーンに保たれています。なので、そこで原稿に書いてある通りの方法で環境を作り、本当にそうなるか試してみます。

すると、執筆者の環境ではうまくいっていたけれど、編集者の環境ではうまくいかないなどの齟齬がある場合があります。そういう細かいところをブチプチと潰していく、けっこう地味な作業をします。

- 小難しいけど、そこをツッコムと本筋が見えにくくなるとき

できれば、読者には文章に書いてある本筋を追っていただきたいのですが、たまに、ちょっと難しい用語がでてきます。しかも、それは本論にはそこまで関係が深くないと判断した場合には、注を補ったりします。

5. 記事をadminにセットする

記事を掲載するadmin画面にjade形式のテキストをセットし、それをステージングサーバーに公開します。そして、執筆者が立てたissueにコメントする形でそのURLを書き込み、申し送り事項とともに、執筆者にチェックをお願いします。

編集済みのjadeファイルは別のフォルダにコミットします。このときにコミットメッセージに以下のようにissue番号を加えると、issueにpushしたファイルへの参照がつきます。執筆者がjadeファイルをすぐ参照できて便利です。

編集済み原稿 著者校正未 #XXX

6. 執筆者（と愉快な仲間達）のチェック

原稿によっては、ここで少しのタイポなどを指摘されて、チェックOKがでます。その場合は、その修正を行ったあと、ふたたぶ記事をセットし直し、issueをcloseして、その記事の校正は終了となります。

変更して、前のバージョンとの差分（diff）は次のように表示されるので、どこをどう修正していったのが、変更の履歴を追うのがとても楽です。

んが、別のエンジニアからもレビューが入ることがあります。

そのような場合は、執筆者はいったん修正用のブランチを切って、jadeファイルに修正を行い、プルリクエストをすることもあります。

プルリクエストというのは、ブランチを切って修正した内容を吟味して、もしOKであれば、masterブランチにマージ（統合）してね！というお願いです。

ここの過程がいちばん、喧々諤々（別に喧嘩しているわけではない）となります。某CodeGridでは3本の記事を毎週配信しますが、編集者の主観からすると、だいたい1本が、ややすったもんだモードになります。

でも、そのすったもんだの先には、ブラッシュアップされた、すばらしい原稿が待っています。ここは執筆者も編集者も校閲者も粘り強くすすめます。

7. issueを閉じる

明けない夜はないように、閉じないissueはない。少なくともCodeGridリポジトリでは。

これでようやく読者にお届けできるレベルの記事ができあがります。ぜーぜー。

まとめ

今回はCodeGridの記事ができあがるまでを、さくっとご紹介しました。エンジニアの時間をかなり割いて行う作業ですので、ヘタすると受注案件よりもコストがかかっているのではないか？と思うことがあります。

幸いにして、CodeGridに関わるエンジニアは単著や共著など、書籍の執筆経験を持つ人がほとんどです。また頻繁にコミュニティの勉強会などでも登壇しています。「難しいことをわかりやすく」という当たり前ですが、難易度が高いことに挑戦できているのも、このメンバーだからなのか？と思うことがあります。

編集者のモチベーションのひとつは「執筆者への尊敬の念」です。これが持てない人は、編集者として不幸です。

だから、私は今日も元気です。どんとこい！クリスマス！

追伸：若干、手前味噌になりましたが、どうぞ、ご海容ください。