この記事はSLP-KBIT Advent Calendar 2016の3日目の記事です．
SLPとは直接関係無いですが，所属している研究室で引き継ぎをしやすくするために，まず新ゼミ生向け教育資料作ってるよという話をします．
求められるドキュメント力
世の中には引き継ぎ案件が溢れています．
引き継ぐ側は、できるだけ詳細な説明のあるドキュメントがあることを望みます．
卒論や修論に関係するシステムは，論文を読めば大体のことは書いているかもしれませんね．
しかし，往々にして十分なドキュメントがあることは多くはありません．
なぜ，十分なドキュメントはあまり無いのでしょうか．
それは書くのがめんどくさいからです．
普段何気なくやっている実験や，どのコードがどんな処理を担当しているのかは
自分でやっていれば大体理解していると思います．
しかし，それを誰にでも(技術レベルの基準をどこに置くかは所属するグループによって異なると思いますが)分かるようにドキュメントを整えなければならなくなったとしましょう．
正直，私はやる気が出ません．
なんだかんだ理由をつけて引き伸ばしてそのまま他のところに行ってしまいたいです．
ドキュメント化，つまり暗黙知を形式知に変換することについては，以前別のブログで触れているので，興味があればご参照下さい.
-> 暗黙知の共有方法の検討
ドキュメント化はめんどくさい．
でも，ドキュメント化して貰わないと引き継いだ人のシステム把握にかかるコストが大きくなってしまう．
ではどうするか．
ドキュメント化の習慣をつけて，ドキュメント化に慣れていくことでめんどくささを減らしていけばいいのではないか．
と考えました．
ということで，ゼミ生がドキュメントを残しやすいように，何をやろうかなーと思っていたら，そういえばうちの研究室では決まった新ゼミ生用の教育資料とか無かったので，それを作るついでに慣れていけばいいかなーということに落ち着きました．
新ゼミ生に教える体制の確立
うちの研究室(香川大学 最所研究室)では，決まった新ゼミ生用の教育資料はありませんでしたが，新ゼミ生に対してゼミ生が何かを教えることが無かったわけではありません．
研究や開発でよく使うVagrantや，Ansibleなどを教えることもありました．
しかし，それらはゼミ生の中でよっしゃやるか！という人がいるときにしか発生しませんでした．
これでは，全然教えてもらえない新ゼミ生の代が出来てしまうかもしれません．
教えてもらえなくても，自分で必要な知識は得ていくとは思いますが，
先輩が導入していた便利なシステムが使えなかったり，アップデートの仕方が分からなくて脆弱な状態になってしまう可能性があります．
こういった状況を防ぐためにも，しっかりとした新人教育資料は必要だと思います．
ここで，ドキュメント化はめんどくさいに帰ってきます．
めんどくさいけど書くようにして欲しいので，とりあえず書くことに慣れて欲しい．
だったら，書きやすいようにテンプレートあるいはフォーマットを作成することが第一歩なのでは...!
という結論になり，テンプレートかフォーマットを作ることにしました．
3通りの媒体?を試してみました．
- パワーポイント
- Wiki(GithubのWiki)
- Github
最初はパワーポイントで作っていたんですが，デザイン考えるのめんどくさいしフォントが違っていたら表示が変になって引き継いだ人が困るかもしれないので辞めました．
次に,Wiki(GithubのWiki)を試してみました．
Markdownで書けるし，差分取れるし最高じゃん！と思ったのですが，目次とかカテゴリ分けをしようと思うとGithubのWikiだとサイドバーだけだし分かりづらいなーとイマイチ．
研究室内で勉強会用のWikiを立てるのもアリだけどちょっと管理が面倒．
最終的にGithubに落ち着きました．
Githubは約束の地
GithubはSaaSですので，こちらで管理しなければならないことがグッと減ります．楽！
さらに，Gitで管理することで差分が残り，資料を弄って消しちゃうのが心配...といった忌避感も減ります．
もちろんMarkdownで書ける！
さらにさらに，Githubに公開していれば，外部の方からのチェックが入る可能性もあるので，誤った知識を残す可能性も減ります！
しかも！公開していることでどの研究室にするか迷っている後輩がGithubを通じて研究室を知ってこの研究室に入ろうと思ってくれるかもしれません!! (ジャパネットたかた風)
ということでGithubで作成していくことにしました．
rookie-training
そんなこんなでrookie-trainingという名前でリポジトリを公開しています．
まだ，パワポでやった内容を落とし込めていなかったり，作成途中の資料があったり，テンプレートが出来ていなかったりします．
Dockerのところだけは大体出来ています．
ここの資料は，
新ゼミ生向け勉強会を開催して，ゼミ生が何人か教えれる場所にいて，一人が全体に向けて説明しながら，一緒に進めていくような流れを
想定して作成しています．
フォーマット代わりに資料作成指針をWikiに書く予定ですが，まだ迷走中でしっかり決まっていません．
仮に教えてくれる人がいなくても，新ゼミ生だけで資料を見れば学習を進められるような対話的な書き方を意識して書くようにしていきたいなと考えています．
研究についてのドキュメントや，研究室内のシステムについてのドキュメントもいつも教えてくれる人がいるとは限りませんし．
作成する資料の内容
研究室では仮想マシンを基本的に利用しているので，
KVM, Docker, Vagrant, libvirtなどの資料を作っていき，
新ゼミ生が自分の研究のときに環境リプレイスで悩まないようにしたいと考えています．
また，プロビジョニングツールで，AnsibleやItamaeも使うところがあるので，それらも追加していく予定です．
基本的にインフラ中心ですね．
また，誰かの研究を引き継ぐ場合に必要な知識(RubyとかGo言語とかDNS, キャッシュ戦略など)を追加して行ければ，ゼミ生のだいたい全員がドキュメントを書く機会を得られるかなーとか考えてます．
やってみた
Dockerについての入門資料をGithubで見れるようにして，研究室内で勉強会をやってみました．
資料自体は，わかりやすく出来ていたので，まぁまぁ好評だったのですが，
勉強会の流れが単調になってしまい，メリハリが無くて眠くなっちゃう内容になってしまったかな〜といった感じです．
課題を出すと，進行度をあわせるのが難しくなると考えて，
資料に書いているコマンドを打って，それについての説明をするといった流れにしていました．
資料に合わせて進めつつ，合間で資料には無い発展した内容を実践してスクリーンに映すとかしてみるのもアリだったかもしれません．
また，Dockerのこんなところが便利でこういうときに使えるんだよ！といったことを伝えきれていない感じがありました．Docker自体が大学生が日常的に利用するようなものでも無いので，実感が沸きづらいのかなーという印象でした．
難しい．
ドキュメントを作成してみましたが，やっぱり疲れますね!
自分の知識自体もあんまり無かったので，色んなサイト見たり本読んだり，実際に動くか確かめたりわかりやすい表現に直してみたり...思いの外時間がかかりました．
作ってみてドキュメント作成に慣れたかというと正直微妙なところです．
言い回しとかはすぐに出てくるようになったのかな，もっと繰り返さないと効果が現れないのかもしれません．
そもそも効果が無いかもしれませんが...
とりあえず，後輩が使いまわせる勉強会資料が出来たのが成果でしょうか．
終わりに
引き継ぎ体制整えよう -> ドキュメント作るようにしよう -> ドキュメント作るのに慣れよう
-> ドキュメント作成に慣れるために新ゼミ生用資料を作ろう -> 作ってみて使ってみた
-> 反省
という流れでお送りしました．
まだ，実践中などの効果があるかどうかは分からないのですが，
ドキュメントがあまり残っていなくて困っている...といった研究室・グループの方は
このような流れでドキュメント作成の習慣を作ってみるのはいかがでしょうか．
それでは!