はじめに
ドキュメントを残さないといけないことはなんとなくわかる。
なのでNotionなりkibelaなり社内で使うツールにちょこちょこドキュメントを残していたりもする。 だけどさ、残したドキュメント見られてます？使われてます？
本当に大事なことは自分が理解できるドキュメントではなく、読者が理解できるドキュメントを残すことなんじゃないか・・・!?
ちなみにタイトルはbingが考えてくれました。
執筆のきっかけ
業務でAmazonPersonalizeを利用した機械学習、推論の作業を引き継ぐこととなった。
事前知識なんてない。全くない。
開発環境の閲覧権限のあるアカウントすら持ってなかった。
そんな中でデータPMの方が引き継ぎドキュメントを用意してくれた。 それをみてポチポチしていけば作業を完遂できた。しかも迷うことなく。
今まで自分が触れてきたドキュメントだと迷ったり、調べないといけなかったり・・・。 挙げ句の果てには違っているので自分で検証して実装変更しないといけなかったり。
聞ける相手がいるならまだいいが、退職などで聞くことができなくなることもある。
もしも自分が引き継ぎ用にドキュメントを残したとして、こんなに綺麗に引き継げるものなんだろうか？僕はこれまで何も考えず、クソみたいなドキュメントを量産するマシンだった。
自分の課題の言語化と同時に、記事にしちゃおうと思った次第です。
引き継ぎドキュメント10ヵ条
個人的にどこを意識すると良さそうかを10項目考えました。
本当はもっとポイントはありそうだし、気をつけなければならない優先順位などもあるのかもしれない。キリがないので10項目に絞らせて欲しい。
ここからは実際にドキュメントを残す感じで書いていきます！
1. 対象読者の明確化
前提条件を明記し対象の読者かどうか早期に判断できるようにする。
これは何のドキュメントで何をして欲しいのかを短くまとめる。
(例)前提事項 ・ このドキュメントはAmazonPersonalizeを用いてレコメンド用のCSVを作成するための手順書です ・ レコメンドロジックの利用方法 ・ 説明リンク ・ AmazonPersonalizeの概要説明 ・ 説明リンク ・ レコメンドの種類 ・ 説明リンク
- 非対象者の読者が見た場合に読まなくて良い判断を早くさせることが可能。
- 意味を感じ取れない作業は苦痛にしかならないため、何のために何に利用されるのかを明確化する。
2. とにかく簡潔に
難しい表現、伝わりづらいものはキャプチャを入れつつ、必要な情報だけをまとめる。 その際に複数項目を並べる際には表組みも利用する。
下記は各レコメンドロジックのインプットとアウトプットデータのディレクトリ説明の表です。
| 学習用データ | 推論入力用データ | 推論出力結果データ | |
|---|---|---|---|
| サービスレコメンド用 | fulldata/training/ | fulldata/predict_input/ | fulldata/predict_output/ |
| カテゴリレコメンド用 | category_recommend/training/ | category_recommend/predict_input/ | category_recommend/predict_output/ |
- 表組にすることでMECEに表記可能
- 視覚的に理解しやすくする
3. 表現方法を意識
用語の説明を書いていく際には下記を意識し、検索性の向上させる。
- 本質をついた名前をつける
- 社内の用語に合わせる
- 表記の揺れをなくす
(例) ユーザー/ユーザ 売り上げ/売上
4. 肯定し断言する
xxxした方が良いという表現は必須項目であればxxxするという表現にする。
条件付きで実行した方が良いものに関してはyyyの場合はxxxすると実行条件を明記する。
yyyしないという否定表現ではなくxxxするという肯定表現を使う。
yyyに注意するなどはyyyを実行しxxxするのようにすべき行動で記載する。
(例) 誤： 条件A**でない**場合には、項目Xを選択する。 正： 条件B、Cの場合、項目Xを選択する。
- 肯定系で漏れなく書くことで具体的に作業をイメージ可能。
- 多少文章が長くなる可能性もあるが、迷うことがなくなる。
5. 手順を具体化する
入力不要、選択不要も含めて、通るであろう手順に関わることはすべてもれなく具体的に記載する。
(ポイント) ・ 別ページ参照などと本文中に書かない ・ 後から質問されないであろう粒度まで具体的にする ・ 後任者が行うであろう動作を考えたうえで説明する ・ 何かを入力していく項目画面であれば入力値を明記する ・ 注意点があれば本文中には残さずコメントに残す ・ 円滑に実行させることだけにフォーカスする
- ドキュメントの読者がどのような動きをしているかを想定したうえで記載していくとスムーズに作業を完遂できる。
6. 節目で確認可能にする
途中で確認できるのであれば、確認タイミングを挟む。
その場合は実行ボタンを押下したか？(yes/no)のような聞き方ではなく、押下後に起きているであろう事象を明記しておくことで確認可能になる。
(例)実際のドキュメントより抜粋 ・ category-to-categoryレコメンドのレシピを作成(モデル学習)する。 ・ Solutions and recipesの設定画面を開く。 ・ 作成したjobが「create in progress」になっている事を確認する。
7. 道の一本化
タスク1~3の処理を実行した後にタスク4を実行しなければならない場合、下記の図のような処理を想像していた。
ただドキュメントに落とし込む場合にはもっとシンプルで良い。
- とにかく道の一本化させる。
- 途中で道が分かれるのであれば別ドキュメントに分けるなど工夫する。
8. 資料は最新の状態で書くこと
過去にまとめた情報からピックアップして作らずに最新の状態を元に書く。
現状の仕様に合わせた書き方でなければ読者が勘違いする可能性は多々ある。
9. 資料は後任者と確認すること
引き継ぎ後に質問が来て場合作業が止まった経験がある。自分にとっても相手にとっても時間のロスにつながる。
相手がどの程度理解したかを実際に試しながら確認を実施することで質問が来ない状況を作る。
試運転に勝るものはない。通して実施した際にドキュメントの不備も見つかる。
- 試運転で問題がなければ安心して業務を任せることが可能。
- 後の時間のロスをなくすことが可能。
- 疑問点があればドキュメントをアップデートを実施。
10. ドキュメントのオーナーを移譲すること
前任者のさらに前の前前任者からの秘伝のドキュメントをもらった経験が何度かある。 間違いを修正して良いのか悩んでしまいドキュメントを更新しないことも多々あった。
- ドキュメントのオーナーを移譲しメンテナンスを後任者にまかせることで最新性を保つ。
まとめ
引き継ぎドキュメントは、後任者への円滑な業務引継ぎに欠かせません。
あらかじめ引継ぎすることを考え資料を作成することで、担当業務をふりかえる機会にもなり課題を発見し、業務改善にもつなげることができます。
自分の業務を移譲することで、新しい業務、次のステップへと円滑に進めることができ視野も広がります。
使われるドキュメントを書いていきましょう！
雑感
究極とか言っておきながら書いてみたら普通のことしか書いてない。
ただしっかりと考えたうえで日常的に実施していかないと普通はできないのかもしれない。
ドキュメントを書くことは大事。だが一番大事なのは読者への気配りだと悟りました。
