この記事について

サービスの保守・運用を担当している者が日々のissueの解決策とエンジニアと非エンジニア間でのコミュニケーションの際に気をつけるべき点を書かせていただきました。

issueのコメント

担当業務でgithubのissueに毎日触れているので、多くのissueを如何に正確にcloseへ導くかの手法を列挙いたします。
1.コメントは具体的に「〇〇の△△を□□に変更」のように書くべし
2.コメントは再現可能なものにするべし

この２つに尽きるかと思います。
1に関しては、当たり前の中の当たり前ですが誰がいつどんな時にみてもわかりやすいコメントにしておくことで、変更履歴も追うことができますし、その修正に至った経緯も把握することができます。これにより、チーム内での認識のズレなども解消できたり、そもそもの作業者の思考が間違っている場合に修正が可能です。

2に関しては、過去にcloseになったissueから解決方法を探ることができるので、同じエラーの場合はその当時の対処法を試すことで速やかにcloseすることができます。

実際のコメント例

画像①↓

画像②↓

上記の画像は実際のissueの画面です。
画像①と画像②を比較したときに差は歴然かと思います。(※すごく極端な例です)

issueのコメントは最早、自問自答の場だと思っており、思考のプロセスを保存する場所です。
細かい情報を残すことで未来の自分を助けることにもつながる且つ、マネジメントをする側もされる側にも進捗や理解度を提示することができるので、できるだけ具体的なコメントを心掛けると良いかと思います。

エンジニアと非エンジニア間でのコミュニケーション

社内やお客様からの問い合わせも担当しているが、どうしてもシステム内部の詳細なデータに関わることとなると我々から開発チームにヘルプを要請します。
筆者の失敗談を交えて書きたいと思います。

失敗談(※実際の問い合わせとは異なります。あくまで例です。)

営業担当者）〇〇社から「差し替えをお願いした画像が表示されていないようなので原因を調査してほしい」というお問い合わせが来ているので対応を御願いします！

筆者）調査・・・調査・・・調査・・・???
データ上は存在するのに、サイト上には表示さ・れ・な・い?なぜ?
開発チームに依頼しよう！

筆者）開発チームさーん！
〇〇の企業のサイトの新しい画像が表示されないのですが何故ですか??(・∀・)

はい！アウトです！！！
言うまでもなくここから無駄なコミュニケーションがこの先続いたわけです。。。

開発チームへの依頼時に、、、
・現時点で起きている事象
・自分が調査した内容と結果
・調査時に使用したデータ
これらを共有していれば半分で済んだコミュニケーションが2倍の工数を生むことになってしまったのです。

分かりきったことですが、問い合わせる際には気をつけるべきことは、△△をした結果□□になり、その際に使用したデータは××ですと伝えるべきです。

問い合わせ対応がひと段落した後に、開発チームの方からすごく優しい文面でご指摘をいただきました。。。
久々にやらかしてしまい反省しております。

今では、テンプレート的に思い出して使っています。

最後に

書いた内容はエンジニアとして、社会人として当たり前なことですが、昨今のコロナ禍の影響で
リモートワークでの業務に従事している人はIT業界に関わらず増加したかと思います。

対面でのコミュニケーションが難しい環境だからこそ、今一度、見直す必要があると感じました。