縁あって会社の同僚と技術本を共同執筆することになりました。
全員執筆は初めてだったのでてんやわんやになりながらもなんとか無事書き終えはしましたが、「ああすればよかったのかな」と思う事もそれなりにありました。
これから技術書の執筆にチャレンジする方や、次の機会（といっても今のところ予定はなし）のためにメモを残します。
これから執筆にチャレンジされる方の参考になれば嬉しいです。
執筆時の心情とやったこと
執筆準備期間
執筆の話が出たのが昨年の夏頃で内容は AWS 関連の入門書でした。
まずは、出版社の方と大綱スケジュールと執筆内容の認識合わせを行い、大まかな計画（本の章などをどうするか）をたてます。
僕らは年末に re:Invent が控えているので年明けから本格的に書き出す計画でそれまではかるく作業をすすめることにしました。
振り返るとこのあたりで決めごとをきちんと抑えずにふわっと始めたのが後半のバタバタに繋がった気がします・・
執筆初期
re:Invent の影響を受けなさそうなところから執筆していく。
.md 形式で執筆してファイルを GitLab のリポジトリで管理し、執筆単位にフィーチャーブランチを切って執筆を行い、MR を RC ブランチに投げて執筆者以外の二人がレビューするという方法で進める。
期限も緩めで空いた時間に作業する感じだったので特に問題もなく執筆が進んでいく。
執筆中期
re:Invent も終わりサービスアップデートのラッシュも一段落ついたのでメイン部分を書いていく。
ただ、このあたりの時期は業務も繁忙期に入る ＆ 新しい AWS の機能の理解のために勉強する必要があるので執筆作業が滞り、アウトプット量がどんどん落ちていく。
「まだ期間的に余裕があるから大丈夫！」と執筆活動から目を背けて多忙な日々を送る。
執筆終期
期限も迫り焦りも出てくる中、自分たちが書いている内容が必要なページ数に達しているのかが判断がつかなくなってきてアウトプット量を把握すべく、GitLab のパイプラインを利用して .md を PDF に変換する仕組みを組み込む。
.md → Re:VIEW → PDF の順に変換するパイプランを設定して自分たちの執筆量をおおよそだが把握できるようになるが、ページ数がちょっと足りないかもと余計に焦る結果に。
その後、ついでにという気持ちで textlint で文章のチェック機能を導入。すると恐ろしい量の error が発生。確認するとルールのメンテナンスが必要なので対応を諦める・・（これが後の苦労の始まり）
執筆環境がローカルに依存している事も気になったので Gitpod を利用して執筆できるようにコンテナイメージや Theia のプラグインを整備。
Gitpod の workspace にテキスト校正くん、vscode-textlint、CharacterCount を導入してファイルの保存時にフォーマットをかけるようにしてテンションアップ。
記載しているプログラムコードのクロスチェックを週末に行い、手順が適切かチェックを行うなど、このあたりは自分の中ではラストスパート感があった。
校正期
なんとか書き上げて出版者の方に製本用の調整をかけていただく。すごく良い感じの出来上がりテンションも上がったがここからが一番つらかった。。
初校が出来上がり確認をしていると、誤字や脱字がわんさかと・・
ここから、再校、念校と重ねていくもその度、誤字や脱字が見つかる見つかる。
校を重ねるたびに全ページ見直してチェックをして今度こそ大丈夫と思っても新しい問題が目につくことで泥沼に・
都度、修正依頼を出版社の方にお願いして訂正してもらうのですが、何度も依頼を出すことになり只々心苦しくなるばかり・・
執筆初期と終期で書き方が変わってしまっており、表記の揺れなども多く確認を重ねるたびに更なる泥沼に陥る。
画面キャプチャも初期に撮ったものと内容が変わっており取り直しと内容追記を行い事になり混迷の極みに。
校を重ねるにつれて修正をお願い可能な期間（＝執筆者の確認期間）が短くなるので業務終了後はひらすら PDF とにらめっこ。
「もうこれで大丈夫だ！」と思っていても新しい校を確認すると不備を見つけてしまうので終盤は完全に自分不信に・
最後は出版社の方のはからいもあり一旦はこれで大丈夫というところまで持っていく事ができ無事入稿。
校正時期が一番しんどかった・・
反省点
振り返ってみてこうすればよかったという点は以下の通り。
textlint の導入の遅さ
技術の執筆はリポジトリでブランチモデルで管理というのはなんとなく知っていたのですが、知っていたていどの知識で始めたので環境周りについて深く詰めずに執筆開始。
基本なんとなくの精神で文字を書くことはできたのですが、文章として適切かどうかを意識せずに書いてしまい、手直しの多い結果になってしまった。
textlint を導入したが時期が遅くルールを自分たちに合わせてきちんとメンテナンスできていかなったのでノイズが多くなってしまい、誤字や脱字を見落とすことになってしまった。
明確化＆厳格化してルールを満たしてない場合は MR を弾くとかそういった対応を最初からやりつつ、適時メンテンナスを行っていれば校正期につらい思いをしなくても良かったのでは？と思ってしまいます。
やっぱり何事も事前準備は大事です。
もっと短期間で集中してアウトプットすればよかった
本格的な着手から入稿まで半年ほどかかったことになります。
お話を頂いた時期から考えると10ヶ月以上の時間を使い執筆を終えました。
初期に書いた内容も AWS の機能が増強されると内容が陳腐化してしまい加筆、修正する羽目に。
すべてが無駄になったわけではないですが結果非効率な時間の使い方になってしまいました。
増えた機能を追いかけるとあれも書きたいこれも書きたいという欲求に駆られてしまうので後ろ髪を引かれつつも我慢。
進歩の早いクラウドを対象にするのなら短期間で最新の情報を本に含めて出版しないと内容の陳腐化が早いと痛感しました。
良かったこと
結構あったので共同著書に参加して良かったと感じています。
業務上接点の殆どないメンバーと情報共有ができた。
拠点や事業部が違うので殆ど接点のなかったメンバーと色々と情報共有しながら執筆は、新しい知識を得る機会になって良い刺激的になります。
主体的な行動ベースで執筆がすすんだ
誰がリーダーということもなくその時に対応できる人がアクションしていくことでいろいろな作業が進んだ。
自分を含めて 3 名だったので意思決定もスムーズに進み、出版社の方とのやりとりは気づいた人が適時対応するという形で「誰かがやってくれるだろう」とやるべきことを後回しにすることはなかった。
リポジトリのメンテナンス等も人数が少ないがゆえに「やっときますー」の一言でさっとやれるフットワークはやはり大事です。
意思決定に時間がかかると「面倒くさいからいいや」って気持ちが強くなる事が多いのでフットワーク軽く物事をすすめることができたのでストレスがなかったです。
GitLab の理解が進んだ
個人的には GitHub で事が足りるので GitLab を利用するのは執筆が初めてでした。
執筆当初は GitHub は無料ユーザーのプライベートリポジトリはコラボレーターが 3 名まで（だったはず・・）という制約があった。
そのため、プライベートリポジトリのコラボレーターの人数制限のない、GitLab を利用して執筆を始めた。
(今は GitHub もコラボレーターの人数制限もなくなっている。）
textlintを導入時にパイプラインを組み込んで、同じものを GitHub Actions にも用意したので自分の中で一気に理解が進んだのは収穫。
もう、GitLab はお友達。
本を書くという事がいかに難しいかがよくわかった
typo の多い自分としては、お金を出して読んでもらうための文章を書くというのは非常に気を使う作業だった。
書きたいことはたくさんあるがその中で対象読者に伝えるべき内容を吟味して書くというのは文章を書くための良い勉強になった。
当然のことながら、要件定義書を書くのとは全く違う難しさを経験して理解できたのは大きな収穫。
これぞまさしく、百見は一触に如かず。
クラウドな執筆環境を用意できた
文章を書くのは、Gitpod でリポジトリは GitLab。
PDF を作るのは GitLab のパイプライン。
すべての作業はブラウザ上で完結できるので基本どんなマシンでも作業ができる状態にできた。
ローカルでの作業は作業終盤の大きくなった PDF のプレビューのみ。
クラウド時代の執筆環境の入門としてはまずまずな手応え。
次あればやりたいこと
反省点の改善は当然としてそれ以外にも以下の事をやってみたい。
クラウドな執筆環境を更にすすめる
これからは、GitHub にリポジトリをおいて GitHub Codespaces で執筆。 GitHub Actions で PDF 作成とかになると思ってる。
（早期アクセス権持ってないので使い勝手はわかりません。あくまで予想・・）
Chromebook を使ってブラウザ上でお手軽に執筆が完結する日もそう遠くないと信じたい。
ただ、この構成は GitHub がおちたら何もできなくなるので全てを GitHub に依存していいのか？ってことをきちんと考えないといけない。
まとめて管理することで得れるメリットは大きいので GitHub さんにおちないように頑張ってもらうしかないかな。
最後に
色々と書きましたが、初めての事だらけで「ああすれば良かったのかなー」とか思うこともたくさんありましたが、手探りで勧めながらも貴重な経験も多くあり、個人的良い経験になりました。
機会があればチャレンジした方が良いこと間違いなしです！
この経験を生かしてもう一回くらいチャレンジしてみたい。
けど、カクテイシンコクメンドクサイナ・・・
おまけ
今回の執筆活動で利用したものをベースに .md ファイルを PDF に変換する CI を含む GitHub と GitLab のリポジトリのテンプレートを作ってます。
興味があれば利用してみてください。
