ポエム
poem

[DRAFT] Why you must not ask questions on Github issues

More than 1 year has passed since last update.

この記事は Github issue で質問してはいけない の英語版の下書きでした。
この記事と同内容の記事を Medium に投稿しました。 Why you must not ask questions on Github issues

もともとこの記事を書き始めたのは、Github issue に来た質問を閉じるときに「なんで issue で質問したらいけないのか」を教えるためにURLを書きたかったのに、言いたいことがまとまった記事が見当たらなかったからです。
なので、私と同意見な方は、質問 issue を close するときにぜひリンクを張ってください。

TL;DR: Asking questions on issue tracker may be DoS attack to developers. Use user forum for discussion, if it exists.

Background

Before Github era, many OSS projects had both of issue tracker and forum (BBS or ML).
Users discuss on forum and report bugs to issue tracker. Issue tracker was place for
issue tracking.

When user ask a question on forum, another users helped him.
It breeds "user community". Asking question is one form of contribute.

But, since Github doesn't provide forum, many OSS users start asking questions
on issue tracker in recent days. At first, small project started mixing issue tracker
and forum. And now, there are many users ask questions on issue tracker even if
there is link to forum in README.

If developer has enough time and mental energy, and number of users are small enough,
there is no problem.
But when developer lacks time or energy, asking question on issue tracker may
cause "burn-out".

Why asking questions on issue tracker cause "burn-out"?

Organizing issue has cost

If important bugs are leaved long time, quality of the project will be worse.
So developers pay significant efforts to organize and triage issues.

And sometimes it's difficult to distinguish between question and real issue by reading only title.
That's why an issue for a question robs time and energy of developer.

Developer : User ratio

If the ratio of developers : expert users : normal or new users is 1 : 10 : 1000,
developers' time is 1000x important than normal user.

Most of expert user doesn't check issue tracker often as developers.
When asking a question on issue tracker, developer will reply it even if
other users can reply it.

So, asking questions on issue tracker not only robs developers' time,
but also robs chance of growing user community too.

Developers may be not good at English

I'm not good at English. Reading English is far harder than reading Go, Python, and even C code.

There are many OSS developers like me. We use English with significant effort.
Replying to easy question may be not easy as you think.

Sometime, I took 10 minutes to read question, 3 minutes to read Python code to reply
the question, and 15 minutes to write a response.
(If they tried to read source code, they might get answer sooner, and they could learn
more than reading my poor English response!)

After I lost mental energy by private reason, I stopped paying my energy and time to be
kind to not malicious easy questions.

What should users do?

When you want to ask a question, keep followings:

  • Read README carefully
  • If there is user forum, don't use issue tracker to ask a question
  • If there is no user forum, consider StackOverflow.
  • Pay your own time and effort to solve your problem
  • Write complete information at first as possible: reproducible code, OS, version, full stacktrace, etc...

FAQ

Q. I don't know is this a bug or my usage is wrong

A. Until you have confidence it's a bug, it's a question, not a bug report.
Ask in forum, and if it seems bug after discussion, file a bug report to
issue tracker with URL and summary of the discussion.

What I want to developers think about

Even if you has enough energy and time for now, setup user forum is good because:

  • When you're like to burn-out, you may not have enough energy to start user forum.
  • Educating OSS users to not use issue tracker as forum may help other OSS developers.

Possible solutions for user forum

Stackoverflow is designed to polish questions and answers.
Polished questions and answers are reusable knowledge.
If there are many knowledge in the StackOverflow, many users can solve their problem by Googling.

gitter is chat service. Unlike slack, group in gitter is lightweight and
bound to Github organization.

Google groups is easy to use ML.
But young people don't like using mail. And it's not Markdown friendly.
So it may be difficult to navigate users to Google groups.

Instead of ML, I propose to create empty Github repository named "project-forum".
Issue tracker on the repository can be used as forum.
People familiar with Github (and Github-flavored Markdown) may love it than Google groups.
Additionally, you can assign some users to organize the repository.