少し前のことになりますが、ZennでSAMLに関する本を書きました。
そのことについてざっくりまとめておこうかなと思い書いてみます。
どうして書こうと思ったのか
そもそもなぜ本という形で書こうとおもったのかですが、それはSAMLに関する体系的な日本語の情報があまりにも乏しすぎたからです。
自分もSAML認証の開発に携わりました。作るにあたって色々調べたんですが、SAMLに関する体系的な日本語の情報は見つかりませんでした。
表面的な仕様や仕組みについての記事は色々ありましたが、じゃあ実際実装するにはどういうことに気をつけないといけなくてどうすればいいのか、なんてことまで書いているものはありませんでした。
こんなにもSAML、SAMLと言われるのに情報ないじゃん…どういうことなの…。つらいじゃん…。
結局仕様を読んだんですが、正直、仕様を読んでもピンときませんでした…。
何パート何百ページにもわたり、あちこちで似たようなことたくさん書いてて全く分からん。
どうにかこうにか機能を追加でき、１年ほど運用していくと、かなりの知見がたまってきました。
この状態で改めて仕様を読んでみると、読める…読めるぞ…と意外と理解できるようになっていました。
（分かるようになってから読んでも、とんでもなく読みにくいことには変わりなかった…。）
この苦しみ得た知識をアウトプットすることで、我々みたいなつらい思いをする人が減るのではないか、需要が絶対にあるはずだと思い書き始めました。
（書き始めてからしばらく経って開催されたWeb24のIDのセッションでもSAMLの本が欲しいという話が出ていたので、早く書かなきゃ日本初じゃなくなっちゃう…と焦りました。）
あと、これを出すことで、もっといろんな人がSAMLについての技術的な記事を書いてくれるといいなという想いもありました。
どうしてZennにしたのか
技術書典で電子書籍として頒布するということも考えましたが、一番はじめはZennが良いだろうと思いました。
書籍という媒体を考えた時、最初からある程度完璧なものとして仕上げる必要がありますが、Zennはいつでも気軽にアップデートが可能です。
これはつまりMVPの状態でリリースができるということになります。
ひとまず最低限の状態で出してみて、ユーザーの反応をみながら改善していけるだろうと思ったので、Zennにしました。
結果としてとてもよかったです。
全部を書き切る前にリリースしたんですが、かなり多くの方に刺さったみたいでよかったです。
執筆の流れ
Zennで書くと決めてからは以下のような流れで進めました。
本という形でまとめるのは初めてだったので、ひとまず技術記事やドキュメントを書く延長で進めてみました。
- アウトラインを考える
- 仕様を読みながら肉付けする
- 全体を通して読んでみる
- わかりにくそうなところの構成を変える
- 全体を通してもう一度読んでみる
- 書いた内容を元に社内で勉強会をやる※
- 勉強会で話した内容を元に、口で追加で説明してしまったところなどを書き加える
- 完成
※所属しているチームでは毎週2日30分ずつ朝の時間を使ってのラーニングセッションという試みをやっていて、その中で枠をもらってやりました。
執筆期間
だいたい半年ほどかかりました。
アウトライン〜構成変更までで半年、それをもとに勉強会やらで半月くらいって感じです。
改めて仕様を読みながら書いていたので、とんでもなく時間がかかってしまいました。
仕様内であちこちに参照が飛びまくるので大変つらい。一方ではこう書いてるけど別のところでは別のこと書いてるじゃん、みたいなのもよくあり、整合性をとるのに非常に手間取りました。
書いてる中で仕様を読んでる時間が7割くらいです。
あと、一通り書いてから読んでみると構成を一気に変えたくなる瞬間が結構あって、その破壊的変更をちまちま直していくという作業が結構時間を食いました。
アウトラインの時点で相当考えてよっしゃこれでいくぞってなっても、結局のところ途中で書き直すことになったので、最初はあんまり時間かけなくてもよさそうです。
感想
本という形でまとめるのは大変むずかしいということがわかりました。
本をコンスタントに出してるひとはすごい…。
ある程度誰でも分かるように大量の情報の中から情報を整理し、取捨選択し、再構成し、書く。
SAMLはほんのちょっと分かる程度で完全にものにしているわけではないので、大変でした…。
終業したあとに執筆作業をやって、土日もやって、ってのを最後の1,2ヶ月は根詰めてやってたんですが、寝る直前まで書くのは良くないですね。
頭が全然切り替わらなくてうまく寝れない状況が続きました。
寝る2時間前くらいには終えて頭から追い出さないといけないですね。
あと、フィードバックがなかなか無いことに対して、かなり不安を覚えました。
何らかのフィードバックがあったのは購入数のうち4,5%くらいですが、なんらかの反応をいただけるのはとてもありがたかったです。
反応がないと、わかりにくかったのかなとか、変なこと書いてたかな…と悶々となっちゃいます。
自分もしっかりフィードバックしていきたいなと強く思いました。
さいごに
いろんな人の目に留まったみたいで、はてブの一番上に自分が載ってビビりました。
OpenID Foundationの理事長までRTしてくれたのでビビりちらかしてました…。
思ってた以上に拡散されたので、間違ったこと書いてて叩かれないかな大丈夫かな…とめちゃくちゃ心配になりましたが、そんなことは杞憂で終わりました。
情報がないことに対して、みんな分かると言っていて、わかるよねわかるわかる…ってなりました。
まだまだ書けていないところがあり、今もまだ書いている最中なのですが、もうすこしで追加分が書き終わりそうです。
また、来年の技術書典では電子書籍と紙の本もだそうとしており、知り合いに表紙の絵だったりデザインだったりを頼んだりとまだまだ大忙しです。
絵はもう上がってきているのですが、めちゃくちゃ最高です。
（一方、いま時点で電子書籍化の作業の進捗はゼロです。助けてください。）
Zennだけではなく、技術書典、Boothなど様々な場所で手にとっていただけるよう頑張っていきたいと思います。
最後に、業務で得た知識を本として出したいということに対して快くOKを出してくださった社長と部長、レビューしていただいた方々、ラーニングセッションに付き合ってくださったチームのみなさま、ありがとうございました！
※ というわけで、このブログはヌーラバーブログリレー2021 19日目の記事でした。
