Issueを立てていただくよろこび

20年を超える製品の開発をしています。開発として、"Issue" を立てていただくことの喜びについて書いています。

ここまでのあらすじ

なぜ開発チームは私の起票した要望をなかなか実装してくれないの？への苦悩 - Qiita
という記事で、以下のようなIssueが登場したストーリー仕立ての小話を書きました。で、社内で勉強会までしました。端的には「我々はそれどころじゃない！」という話です。

「このワーニングメッセージ、句読点（、。）がカンマ・ピリオド（，. ）になっていてなんというか、イケてないというかダサイです。サクっと直してくれませんか」

...
...
( ﾟдﾟ)ﾊｯ!

...要望、冷静によく聞くと直さなくても業務全体の進行を妨害するほどの支障はないっていう話に聞こえました（何ということだろう、この時点で彼はもうほぼ思考停止しているのだ）。この案件、異議あり！！！

判決、先送り。

続編

上の記事ではIssueが結局、先送られるという悲しい結末を迎えました。Issueって困りごとなのでしょうか。Issueを起票したい側にはこんな疑問が出てきますよね。

Q. 不具合報告、案件要望ばかりで迷惑かけていないかなあ？
Q. しかし本来、不具合報告、案件要望はとてもとても嬉しいものでは？
Q. 皆が幸せになれる、喜ばれる不具合票の書き方があるはずでは？

以上を動機に、今回の記事では「皆が幸せになれる、喜ばれる不具合票の書き方」を考えてみる。
Issue。不具合票だとか案件、要望などと色々呼称があるがここでは一般的な呼称「Issue」と、動機とした元記事「Issueを立てるな！」をリスペクトして、総称してそう呼んでいくことにします。

以下を参考にしています。
「Issueを立てるな！」 - Qiita
「雑に立てられるIssue」で疲弊しないためにOSS開発者ができること - 2021-12-04 - ククログ
 OSSのゆく道：Faker.jsの顛末｜Takahiro Ito｜note 等など。

「Issueを立てるな！」

「Issueを立てるな！」論旨としては以下のようになります。

Issueを立てられることの嬉しさは当然わかる。
- しかしそれは「人気のないプロジェクト」において注目されることの嬉しさである。
- フィードバックそのものが嬉しいというフェーズの話である。
人気のあるプロジェクトでは話が変わる。
- 人気プロジェクトの運営者は疲弊している...。

一方「雑に立てられるIssue」で疲弊しないためにOSS開発者ができることでは以下のようにも書かれています。

(開発者が報告者に対して) 軽率な行動を咎める方向での提言や、相手をビビらせて追い払うような対応の仕方で、「質の低い報告が減り、開発がより快適に行えるようになる」効果が得られるだろうか。
- それについては懐疑的。
- 真に開発者を困らせる雑な報告をする人は、そもそもそういった提言を見もしない。
- 気にも留めない。
- 一方で、善意ある慎重な報告者が「もしかしたら、自分のしようとしているこれは迷惑なのかもしれない……」と報告自体を尻込みして去っていく。
「協力してくれる意志やポテンシャルがありそうな人への門戸は開きつつ、質の低いIssueや無責任な人を遠ざけられるであろう方法」を共有したい。

注意深く書いておきたいが、必ずしもOSSの流儀や悩み事が商用製品におけるイチ開発担当の悩みに当てはまるとも思わない。プロの開発者とプロの運用者、顧客担当がサポートする製品、また製品の歴史いかんでは、アプローチも異なる。
一方で「20年」等というプロダクトの実績を考えてなあなあになっていたり今更、秘伝のタレ化した部分、明文化できていない部分もある。そんな開発担当の立場から、「Issueを立てていただくよろこび」を改めて考えた。

人気OSSプロジェクトの運営者は疲弊している = 20年を超える「レガシー」製品の開発者も疲弊している？

例題

「このワーニングメッセージ、句読点（、。）がカンマ・ピリオド（，. ）になっていてなんというか、イケてないというかダサイです。サクっと直してくれませんか」

なぜ開発チームは私の起票した要望をなかなか実装してくれないの？への苦悩 - Qiita での1トピックです。

「イケてない」。
...「それってあなたの感想ですよね」なのですよね。
どう「イケてない」のかを定量的、定性的に表現していきたいです。例えば、

～～なスキルレベルのお客様が～～で戸惑ってらっしゃった
こういう順で操作しているとここに唐突にこのメッセージが出てくるため誤解を招きやすい

踏まえて

「Issueを立てるな！」をもう一度よく見てみたい。

人気プロジェクトとなると、話が全然変わってきます。
真っ当な issue の対処だけでも大変ですし、さらに日常的に

要領を得ない機能要求
要領を得ない質問
要領を得ないバグ報告
実装の都合も、他の利用者の都合もガン無視した本人の都合全開の機能要求
不正確なバグ報告
README に書いてある事すら読まずに投げてくる質問
、、、等々、手間暇かけさせられひたすら消耗させられるだけの issue が立て続けられます。
モノにもよりますが数としては１つや２つでも、メンタルにクる時はかなりキます。

これらが色々な現場に共感を投げかける。「モノにもよりますが数としては１つや２つでも、メンタルにクる時はかなりキます。」はわかりやすいです。そしてそれは顧客対応の現場、コンタクトセンターなどなどでもややもすれば「コミュニケーションの問題」や「スキルの問題」等として処理されがちではないだろうか。

「issueを立てよう」

「issueを立てるな！」も、つまりはIssueを立てようと述べているのです。

パフォーマンスがそのプロジェクトの至上命題である場合ですら「最適化するな！」というベストプラクティスは有効です。無闇に最適化を施せばメンテナンス性を損ない競争力を失い、結局はパフォーマンスも出せなくなる為です。

もちろん、最適化が必要な場面はあります。しかし、それには事前にプロファイリングを行い、最適化を施したコードの速度が、犠牲にしたメンテナンス性に見合うモノであるか慎重に判断する必要があります。

Issueも同じです。本当に必要なissueは立てましょう。

立てましょう。
その要点。以下がIssueを立てる際のコツです。

過去Issueに類似したものはないか。
関連する範囲のドキュメントには全て目を通したか。
不具合報告なら以下を適切に選択する。
- バージョン
- Expected (こうなる事が期待されるが)
- Result (こうなった)
- 再現環境 etc...
立てたIssueには責任を持つ。
開発者からの質疑には、必ずなんらかのリアクションを行う。

どう立てる？

事実と意見を分ける。Templateやガイドラインを守る。です。
以下がポイントです。

事実と意見を分けて書く。
原因と結果を分けて書く。
問題点を明確にする。
時系列を正確に書く。
時制（過去・現在・未来）を明確にする。
何をしてほしいのかはっきり書く。
つまり開発者にわかるように書く。
チケットの具体的な書き方
- 概要・タイトルの書き方に気をつける。
- 問題の全容がわかるように書く。
- 識別できるように書く。
起票時の記載内容
- 完了基準を明確にする。
- 重要度の判断をする。
文章の書き方
- 一文を短く書く。
- 箇条書きで記載する。
- 敬語や修飾語を省く。
文字にこだわらなくとも、画面キャプチャあるいは、Gif動画でも https://www.cockos.com/licecap/

参考記事

読まないといけないもの、いっぱいあるなと思いますよね。
でも意外と、身近な開発者の方はもうテンプレートを作ってくださっていたりもします。そうです。一度「起票の要領を得ていなかったら教えて下さい」と勇気を出して頂くのも手です。

Q. 不具合報告、案件要望ばかりで迷惑かけていないかなあ？

A. そんなことはありません。不具合報告、案件要望は、大事な大事な「お客様の声」そのものです。機能開発のヒントになる宝の山です。

Q. しかし本来、不具合報告、案件要望はとてもとても嬉しいものでは？

A. Yes. まちがいないです。本来それらは大事な機能強化のヒントなはずです。

Q. 皆が幸せになれる、喜ばれる不具合票の書き方があるはずでは？

A. これこそYes. あります。テンプレートやガイドラインは、その幸せへたどり着くためのテンプレート、ガイドラインのはずです。ぜひ参考にしてほしいです。

もちろんソースを直せる開発者は、これを見てMRを書きましょう。
Merge Request (Pull Request) の書き方 - Qiita

他意見

[B! OSS] 「雑に立てられるissue」で疲弊しないためにOSS開発者ができること - 2021-12-04 - ククログ
 [B! OSS] 「issueを立てるな！」 - Qiita

以上、Happy Issuing!
参考になればさいわいです。

Issueを立てていただくよろこび - うれしい問合せ・不具合起票