📖

Re:VIEWとGitHubを使って、技術書合同誌を書いた話（非エンジニア含む）

2020/09/20に公開

GitHub

技術書

review

idea

この度、C98エアコミケでまんてらスタジオというDiscordのグループのメンバーで合同誌を頒布しました。しかも2冊。
内容の詳細は以下のツイート等をご確認ください。

さて、今回執筆するにあたり Re:VIEW と GitHub を使用して執筆環境を構築したのでそれについて説明したいと思います。

これまでの製本方法

まんてらスタジオでは既に C96 と C97 で2回ほど合同誌を発行しています。
その際、GoogleDocument と Markdown を使用しました。
ただ、どちらの場合も問題がありました。

GoogleDocument だと各々が自由なスタイルで書くのでフォーマットの統一が難しい
Markdown だと、フォーマットの統一は出来たが目次の生成やページ番号のなどの「本」としてのクオリティをあげるのが難しい

上記の問題を解決する為に、今回 Re:VIEW を使って執筆してみることにしました。
（ちなみに私は今回から運用チームとして参加することになりました）

Re:VIEWとは？

Re:VIEW 公式サイトより

Re:VIEWは電子書籍と紙書籍のための、簡潔かつ強力なデジタル出版ツールです。コンピュータ書等の技術書籍（紙・電子）の商業出版や同人出版に利用されています。

今回は PDF に出力する機能のみを使いましたが、ePub などの形式でも出力できるようです。
最近では技術書典などでもよくつかわれています。
目次の自動生成など本としての体制を整えるのに有用と判断して利用することにしました。

Re:VIEW Starter の利用

設定周りが少し自信がなかったのと、C98 がゴールデンウェークに行う関係で準備期間が十分に取れなかったので、今回は Re:VIEW Starter を利用させていただきました。
初期設定を GUI で行えたり、LaTeX の知識がなくても既に調整されているので初心者でも使いやすいという特徴があります。
詳しい説明は製作者のQiita記事があるのでそちらをご覧ください。

GitHub を利用した執筆について

今回、執筆は GitHub を利用して行うことにしました。
これには２つ理由があります。

1. 執筆者の増加に伴う管理コストを抑える

元々は GoogleDrive を利用してファイルなどのやり取りを行っていました。
しかし、C98 に向けた合同誌は2種類作成するので更なる執筆者の増加が予想されました。
GoogleDrive でやりとりでは管理コストが人数が増えるほどかかることになります。
GitHub を活用することで、執筆や校正などの管理コストを抑える狙いがありました。

2. Re:VIEW のビルドの難易度

Re:VIEW（Re:VIEW Starter）を自分の PC でビルドするには最低限の Docker の知識が必要になります。
しかし、今回エンジニアでない人や Docker に慣れ親しんでない人も多くおり、その場合 PDF のビルドするのは難易度が非常に高いです。
後ほど詳しく説明しますが、GitHub Actions を活用することで GitHub に push することで誰でも PDF のビルドを行えるようにしました。

GitHubを利用した執筆フロー

大まかな構成は以下のようになります。

実際に執筆の順を追って説明していきます。

執筆の準備をする

まず執筆環境を構築する必要があります。各執筆者ごとに下記のような専用のプルリクエストを用意しました。

これは Git に不慣れな人もいるのでブランチ運用をシンプルにする為に、１執筆者に対して１PR（1ブランチ）という形にしました。
また、ブランチ・PR の管理コストを下げる狙いもありました。
この指定された PR のブランチを clone して執筆してもらいます。

執筆を行う

指定されたブランチで PR に書かれている「編集可能なファイル・フォルダ」のみ編集してもらいます。
他のファイルをいじるとコンフリクト等が発生する可能性があるので基本的に禁止していました。
この運用で執筆に大きな支障はありませんでした。

製本されたPDFを確認する

PDF で確認する方法は2通りあります。

一つ目は GitHub に push して CI で生成されたものを確認する方法で、誰でも簡単に出来ます。
GitHub Actions の設定方法はこちらの記事に書いてるので、詳細はそちらをご確認ください。
GitHub Actions を使って Re:VIEW Starter の PDF をビルドする

二つ目は docker のイメージを使ってビルドする方法です。
Re:VIEW Starter にはビルド用の dockerイメージが用意されているので、そちらを利用してビルドを行います。
make コマンドを利用して

make build

で簡単にビルド出来るようにしています。

執筆の完了

執筆が完了したら全てコミットしてプッシュしてもらい、PM に確認を取って一旦執筆は完了になります。
一旦この状態で PR はマージされます。

校正

一旦執筆が完了した後はそらまめさんによる校正が行われます。
校正は各執筆者ごとに校正ブランチを新たに切って PR を出してもらいます。
各執筆者はその校正内容を PR 上で確認して、承認もしくは訂正を行います。
校正が完了したら執筆者の作業は終わりです。

校正以外に書き忘れなど訂正したい箇所がある場合は新たにPRを作って修正対応を行いました。

Re:VIEWの記法に関して

Re:VIEWの記法は慣れてないとちょっと書きにくいです。
そこで、よく使うであろう記法については wiki に「Re:VIEW 記法チートシート」という形でまとめておきました。
また、チートシートの記法で Re:VIEW Starter でカスタマイズされた記法を使うことで、優先的に使ってもらう為という目的もありました。

それとは別にMarkdownに慣れている人もいるのでMarkdownとRe:VIEWの対応表も用意しました。

全体への周知方法

今まで説明してきた内容を全体に周知する為に事前に wiki にまとめました。
また、執筆に関係なくRe:VIEWの構成などの話も記載しており、最悪自分がダウンしても運用可能な形式を目指しました。

Gitを習得してない人への対応

GitHub を使う前提なのでGitを習得してない場合は執筆が困難です。
そこで、今回以下の2通りの方法を提案して執筆者に好きな方が選んでもらうことにしました。

Git の使い方を個別にレクチャーをして、今回の執筆で必要になる最低限のGitについて学習する
Google Document で執筆してもらい、後ほど運用チームで Re:VIEW に書き起こす

Git のレクチャーを行う場合は Discord の画面共有で手元を確認しながら、音声で指示しながら説明を行いました。
執筆の流れ自体は上記と同じです。

Google Document を使い際は、校正も含めてすべての執筆作業を Google Document 上で行いました。

実際に行った際の問題点について

この方法で「新しい挑戦をしたい時に見る本 Vol3」と「自分が挑戦した時の話を語る本」を執筆して感じた問題点について書いていきます。

1. 執筆の説明がエンジニアでないと理解するのに困難な箇所がある

wiki に執筆に関して説明を記載していますが、非エンジニアの人にとっては説明が難しい箇所があったようです。
そもそも Git を理解している前提で wiki を書いてしまったのでこのような問題が発生しています。

2. GitのレクチャーやRe:VIEWの書き起こし対応のコスト

今回はエンジニアの方が多かったので、Git のレクチャーや Re:VIEW への書き起こしの対応が多くはありませんでした。
しかし、Git 使えない人が増えると運用チームにかかるコストが大きくなります。
そのような場合の対応方法を検討しておく必要があります。

3. PushしないとPDFがビルド出来ず手間がかかる

Docker の使い方がわからない場合は、GitHub に push する以外に PDF を作る方法がありません。
その場合、画像のサイズを調整したり、ビルドエラーを解決する際に毎回 push してビルドを待つ必要があるので手間がかかります。
ビルドのエラーについては基本的に私が確認して解決していましたが、画像サイズに関しては本人が確認する必要があります。

今後に関して

最初の方で上げていた「本」としてのクオリティをあげるという目的は十分達成できたと思います。
しかし、この運用だと非エンジニアでない場合は参加する敷居が高くなってしまいます。
ただ、今回執筆している「挑戦本」や「自語り本」ではエンジニア以外の方も積極的に参加していただきたいと考えています。
今後はより執筆する敷居が低くかつ運用コストが低い執筆環境を模索していこうと思います。