技術スキルの資料作成がつらい

プロジェクトに参入した人が使用している言語が苦手ということで勉強会という名の教育会をすることになりました。

仕事の基本姿勢が資料ベースかつ丁寧な自分に白羽の矢が立ち渋々資料を作成することになりました。そこで辛いことと気を付けたところを書いていきます。

既に知っていることを言語化することはとても難しいです。開発を進めていると言語に慣れてきて、常識と化していることが良くあります。

そのような常識は既に抽象化して知識になっていることが多々あるため、具体化や言語化がかなり難しいです。例で言うと割り算を具体例を挙げずに文字だけで足し算しか知らない人に説明する感じになります。

相手の技術レベルに合わせないと資料を読んでも理解してもらえないものになってしまいます。

それを防ぐために相手に「どれぐらいわかる？」と聞いても、相手にとっては勉強する物は未知のものになるので答えようがないです。さらに、言語や技術は横の応用が効くものになるので他の言語のことも想定しながら資料を作成しています。

フレームワークの概念なども説明するために図を使用できるワードやパワポで資料を作成していますが、ソースコードが資料に向いていません。ソースコードを張り付けるだけで縦に長く資料が見にくくなり、そもそも資料を読む気がうせてしまいます。

そのため、必要最低限のものを抽出して説明の横に置き、全体のソースは付録として最後に置くようにしました。

概念的な説明は図を使用して、視覚的に表現をすることで理解を助けるようにしています。さらに、一つの図に複数のことを詰め込むのではなく、大抵1～3個の図を使って丁寧に説明しています。

相手は開発者なので具体的なソースコードがある方が理解しやすいです。そのため、言語の特徴や使い方はソースコードとセットで書くことで相手の知っている言語との比較からより理解を深めてもらいます。

言語の説明資料を書いていると、複数の要素を一つのソースコードで説明しようとしてしまいます。（例えば、クラスとクラス変数を一緒に説明）

分かっている人から見ると当然別の要素だということがわかりますが、分からない人から見るとわからないものが2つ増えてしまい混乱してしまいます。

そのため、説明とソースコード/図を一つ一つ順番に書いていく必要があります。

正直、自分は説明なしで自分で調べてある程度言語を使えるようになってきたので「自分で調べればいいのに。。。」と思いながら資料を作成しています。

昨年の経験から調べるのに時間がかかる人も往々にしているようで、開発中はそのスピードが致命的になり廻りまわって未来の自分にも苦労が降りかかることになります。

そのため、ある程度時間に余裕のある今に資料を用意して説明しておくことで将来的に質問をされても「この資料を見てね」で済むので辛いけど資料は必要だなと思っています。

日常の色々な事