gitbookで知見共有したら少し幸せになれた話

この記事はTech KAYAC Advent Calendar 2018の5日目の記事です。

こんにちは！新卒3年目になり、楽をしたいお年頃になりました、ゆみこふです。
クライアント事業部のファイ部という部署でWebフロントをやってます。
今回はチーム内の知見共有でgitbookを使ってみたところ、いい感じに運用できているのでそのことについて書こうと思います！

経緯

クライアント事業部では、さまざまな案件が同時並行で進行しています。
なので、自分、ないしは同じ案件にアサインされたエンジニア以外のコードをじっくり見る機会が普段なかなかありません。
一方で、全く違う案件でも同様の技術を使うということは多々あるのですが、
これまではそれらをまとめておく場所がなく

(｡･･｡)「他の案件ではこうやってたよ　つ (案件githubリポジトリのURL) 」
(^q^)「ありがとうございます！権限ください！」
( 待ち時間 )
(｡･･｡)「付与したよ〜」or 「このファイルのここらへん！（ファイルをどかっと渡す）」
(^q^)「みれました！〜〜の部分って何やってるところですか？」
(｡･･｡)「あ、それはこうこうでこうこう〜〜（説明）」

という感じで共有するしかありませんでした。
ググって分かることや参考になる記事を共有しておさまればいいのですが、
実際にやってみたニッチなつまづきどころや、社内で検証した結果の知見（案件情報が入った機密情報含む）が逐一確認できる場所がほしかったのです。
そこで作ったのが「fibe-utiljs」です！

環境構築

gitbookをインストール

npm install -d gitbook-cli
gitbook-cli - npm

プロジェクト作成

gitbook init

ディレクトリ構成

root/
  ├ _book/ ... buildでhtmlファイルが吐き出される
  ├ docs/ ... 元となるマークダウンファイル
  ├ gitbook/ ... gitbookプラグインをいれる
  ├ img/ ... 記事中で使用する画像をいれる
  ├ book.json ... gitbookの設定ファイル
  ├ package.json ... プロジェクトの設定ファイル
  ├ README.md ... 必須
  └ SUMMARY.md ... 目次の設定ファイル、必須

ページを作成する

docs/ 内にマークダウンファイルを作成します。（htmlファイルでもOK）
_hoge.md とした場合、出力されません。
開発はgitbook serve を実行し、ビルドは gitbook build です。

目次をつくる

SUMMARY.md に目次をつくります
こんなかんじです

# Summary
### Async（小見出し）
* [wait / delay](docs/async/wait.md)
* [timer-class](docs/async/timer-class.md)

プラグイン導入

gitbookにはインストールするだけで使える便利なプラグインが揃ってます。
実際に使っているものをご紹介します。

circleci設定

プルリクがマージされたら、自動的にビルドとデプロイをしてくれるように設定します。

できた

f:id:wyumikokh:20181204165750p:plain

① メニュー、検索ができる
② タイトルと概要説明
③ コード、コピーボタン付き
④ JS fiddle を貼り付けられるので、その場でどんな動きをするコードか分かります
⑤ 誰がいつ書いたコードなのか丸わかりです

運用

ルールをきめた

チーム内といえど、いろんな人が見るコードなので読みやすさや使いやすさが担保されるよう、多少ルールを決めました。

  • カテゴリにわけてどんなコードがあるのか見通しよくした
  • レビュワー設定を必須にした
  • JSDoc形式の関数説明を必須にした

issue 駆動

ほしいものはとりあえずissueにしておけば誰かが書いてくれます

slack通知

issueやプルリクコメントなど、slackに通知するようにしました。
そのおかげで、最初はコードを寄稿してくれる人を指名していましたが、
自ずと誰もがウォッチ＆コミットしやすい環境になりました。

3ヶ月後アンケート

つくっても使われないと意味がないので、
運用はじめて3ヶ月後くらいにチーム内でアンケートをとってみました。
コードを実際に利用した人は70%、知見の寄稿をした人は50%でした。
コードを実際に使ってない人は熟練者に多かったのですが、自分オリジナルのutilをあらかじめもってるから、だったりするようです。
そのコードが何をするのか自分で分かってさえいれば、丸コピは誰でもすることです。
また、今は必ずどの案件にもあるような与件に関するutilが主にたまってきている 演出面にも使えるutilもためていけたらなーと思っています。

まとめ

少しの作業できれいなフォーマットが手に入るgitbook、すばらしいですね。
実際に運用してみて、改善したのは以下の点です。

時間削減

  • 実際に使う実装者
    何度も使うようなコードはutiljsからひっぱり、注力すべきところに時間を注げます
  • コードを提供する側
    口頭で伝える時間を削減できました
  • 案件中のレビュワー
    コードレビュー時にutiljsにあるコードがあると安心感があります

コードの品質が上がった

  • コードが多数の目にさらされることで、いい意味でまさかりが飛んできます
  • 上級者のコードの書き方を見るいい機会にもなり、学習の場としても使えます

知見の共有

  • 例えばシェアのインデントなど、いつのまに変わったの？！というAPI最新情報を全体に共有できます。

さいごに

いかがでしたでしょうか？
知見共有手段の参考になれば幸いです！ カヤックでは楽するとこは楽して新しい技術に挑戦したいエンジニアを募集しています★

明日は、美少女のイラストを描くのに定評がある数学者、ねっしー の記事です！
お楽しみに！