背景
私は業務作業中に Notion を用いて作業メモを書くことにしています。この時、ちょっとしたことなのですが「期待通り実行できた」みたいに起こった事象が期待した通りなのか想定外のことなのかわかるように書くようにしています。
ちょっとわかりにくいので次に例を示します。
例 (ここのセクション全てが実際に書いた文章を再現したものです)
本番環境で計算したデータを用いて task_command を実行してみる。
> task_command -r microbiome_data.tsv -s -u user_information.csv
Traceback (most recent call last):
File "/usr/local/bin/hana_gut_v1", line 8, in <module>
sys.exit(main())
File "/usr/local/lib/python3.9/site-packages/task_command/cli/examine.py", line 14, in main
E.examine()
File "/usr/local/lib/python3.9/site-packages/base/examiner/base_examiner.py", line 18, in examine
self.res = pd.concat(
File "/usr/local/lib/python3.9/site-packages/pandas/util/_decorators.py", line 311, in wrapper
return func(*args, **kwargs)
File "/usr/local/lib/python3.9/site-packages/pandas/core/reshape/concat.py", line 360, in concat
return op.get_result()
File "/usr/local/lib/python3.9/site-packages/pandas/core/reshape/concat.py", line 591, in get_result
indexers[ax] = obj_labels.get_indexer(new_labels)
File "/usr/local/lib/python3.9/site-packages/pandas/core/indexes/base.py", line 3721, in get_indexer
raise InvalidIndexError(self._requires_unique_msg)
pandas.errors.InvalidIndexError: Reindexing only valid with uniquely valued Index objects
期待通りエラーを再現できた。
なぜ？
タスク作業中に他の方が読んだ時に、「作業中に詰まってしまって困っている」のかがよりわかりやすくなると思ったからです。
上記の例は本番環境で定期的に計算している解析がエラーを吐いて実行できなくなってしまい、エラーの原因を特定してほしいと頼まれた作業の時のメモです。
まずは本番環境と同様のデータを用いてエラーを再現できるかを試したので、「期待通りエラーを再現できた」とメモしました。
なぜこのような書き方をしているというと、作業をメモしているものを読んでる時は、特にエラーが画面が表示されたら「あれっ？エラーが出ているけど問題ないのかな？」と目が止まりがちかなと思います。エラーとか赤い文字がザーッと表示されているのを見るとヒトはストレスを感じるとも言えますかね？(もちろんエラーに敏感なことはいいことだと思います)
そこで「期待通りエラーを再現できた」と書くことで「これは困りごとが発生したのか、そうでないのか」と読み手が考える必要をなくし、「これは困っておらず想定内のエラーなんだな」とストレスなく続きを読むことができると考えています。
書き方まとめ
- 期待通りである場合 🙆
- 「期待通りエラーを出力した」
- 期待通りでない場合 🙅
- 「期待に反して動作しなかった」
- 「エラーが出てしまった」
皆さんもこんな表現しているよってことがあればぜひ教えてください。
まとめ
読み手がいちいち「これってこういうことかな？」と頭の中で変換する必要がないことが、スムースなコミュニケーションのための大事なことの１つと思っています。
今回は「期待通り」などの表現を加えることでそれが少しでも達成できるといいなと思って Zenn にまとめてみました。
また読み手は同じメモを読む未来の自分であったりもします。
自分のためにもわかりやすいコミュニケーションを心がけたいです。
もちろん主観によるところはあるので Not For Me だという方もいると思いますが、面白いから自分でもやってみようという方が少しでもいましたら大変嬉しいです。
Discussion