読者です 読者をやめる 読者になる 読者になる

yuqlidの日記

どっかの学生の雑記帳

引き継ぎ資料の書き方

はじめに

高専生の皆さんそろそろロボコン2016が始まりそうですね. 大学生の皆さんそろそろ2次ビデオ提出ですね.

シーズンが終わるとみなさんこれに頭を悩ませてはいるのでしょうか?そう,
引き継ぎ資料(技術資料)
(この時期のじゃないというツッコミは無しで)

資料を書こうとして「こんなのこれから先使うわけないだろwww」という気持ちになった方,いるのではないでしょうか?僕ははとてもあります.
「シーズン中ずっと後輩が見てたし,書かなくてもわかるでしょう」 という気持ちになった方,いるのではないでしょうか?そう思っていた時期が僕にもありました.

しかし,その技術(資料)が必要かどうかを決めるのはその技術を開発した人ではありません,来年以降主力になる次の世代が決めるものだと思います.
今後のルールによっては「うちは昔こんなことしてたからなにか技術があるかも」となるかもしれませんし,ずっと使われないかもしれません. 「先輩何も残してないじゃないかよコノヤロウ」なんて後輩が言い出したものなら,
おめでとうございます,めでたくロステク化です.

ではどれくらい書けばいいか?

引き継ぎ資料を書くのはとても労力が必要(とてもつらい) ので,その資料によって読み手が「どれだけのことができるか」という基準で引き継ぎ資料の書く量を決めればいいかと思います.

  • レベル1 その技術の存在を知る
  • レベル2 その技術を運用できる
  • レベル3 その技術に手を加える事ができる

レベル1
まずはここからでしょう.そもそも自チームに存在する技術なのかどうかの確認からです.「どこに眠ってる」,「誰が知ってる」という情報だけでも次の人にとってはだいぶありがたみが違うと思います.

レベル2
その資料を読めば「運用」ができるレベルです.
過去の基板などの使用方法,仕様など知っておけばその技術を自分が使うことができるというレベルです.
ですので「これが何をやっているか」といったことは使う人(次の世代)がわかっていなくても問題ないというレベルです.基板を例にしますが,
「資料通りこの部品買ってきて,手順通りにはんだづけしてどこどこのフォルダにあるhexを書き込めば動く,どこどこのコネクタはこの順番にピンアサインされている.この可変抵抗で調整ができる.このスピードならデータが取り出せる」
と言った感ような.
この段階では,「ソースコードがどのように書かれているか,この抵抗が変化することでなぜ調整ができるか.なぜ部品がその配置なのか」といった情報は必要なく,その技術がブラックボックスの状態でも問題ないということです.

レベル3
その資料を読めば「仕様変更」ができるレベルです.
その技術はあくまでも「開発されたその当時,最適だと考えられて開発されている」裏を返すと「過去の技術が現在の自分たちの求めているものに対して最適だとは一概に言えない」ということです.
つまり場合によっては自分たちの都合のいいように,その技術を改良,仕様の変更したいという場面があると思います.
このためには,「なぜこのように設計されているのか,なぜこのような配置なのか,なぜこの部品はこの値なのか」といった情報が必要です. ここが先ほど言ったレベル2とは異なる点で,その技術がホワイトボックス化されているということです.
ここまで来ると,これまでの技術の経緯(なぜこれを作ることになったのか),当時の状況からくる選定理由(なぜこういった部品を選定したのか),仕様の変更方法と非常に情報量が増えるので次の世代の人にとってはとてもありがたいと思います.
書く人からしたらとても大変ですがね

まとめ

自分が過去感じたことから引き継ぎ資料の書き方を簡単にまとめました.もっと書けなくはないのですがこれくらいで
どうしても聞きたい!という方はtwitterなりなんなりで連絡をいただければまたお話しようと思いますのでお気軽に聞いてください.
また細かい修正をするかもしれませんが,これが資料を書く人の参考になれば幸いです.

ではみなさん,これからもロボコン頑張ってください.