“回答を得やすい質問” と “良い報告” のコツ — ソフトウェア開発を例に
私は最近「日本語 TeX 開発コミュニティ」などのメーリングリストに参加していますので、ここでは LaTeX を例に説明しますが、これはいかなる技術系コミュニティにも当てはまることだと思います。私なりの「技術系コミュニティへの貢献・レポートのコツ」として、ここにまとめることにします。あくまで “理想論” といってしまえばそれまでですが、一部は参考になるかもしれません。
タイトルに「“回答を得やすい質問” と “良い報告” のコツ」と書きました。この2つのポイントはほぼ同じです。みなさんも、学校の授業で質問する場合にまず「自分がどこまでわかっているかを理解し、それを人に伝える」ところから始めると良い回答が得られたという経験があると思います。それと同じことで、ソフトウェアを使っていて疑問に思ったこと・期待どおりにならなかったことを他人に質問する場合にも同じような心がけが必要です。良い質問をするコツは良い報告をするコツと多くを共有していますので、ここでは私の経験をもとに “私が考える良い報告とは” を考えていきます。
LaTeX などのソフトウェアを使っていると、ときどき「これは意図した動作なのだろうか？」「ここがもしこうだったらよいのに」「こういう場合にも対応してほしい」のように思うコトがあります。そのような場合に、「これはそういうものだからしょうがない」として泣き寝入りするのも一つの手ですが、これを上流（＝開発者）に報告したいと思うことがあります。
報告するメリットはいうまでもありません：
- 新しい機能が追加される
- 嬉しくない挙動が改善される
このようなことは、良いレポートがあって初めて成立します。「良いソフトウェアを使わせていただいているのだから、できる範囲で自分も開発に貢献する」、それが特にオープンソースのソフトウェアを利用する上でのマナーといっても過言ではないと私は考えています。
では、良いレポートとは何でしょうか？ それは、「開発者に具体的に再現してもらえるように、状況を詳しく説明する」ことから始まります。まずはレポートする前になにを考えるべきか5つの観点からみていき、それに続いて実際にレポートするにあたっての注意点を述べてみます。これはあくまで私の経験にすぎませんが、だいたいの場合成功していると思います。
良いレポートへの道 (1) ：まずは雰囲気をつかむ
技術系コミュニティの質問掲示板は、知恵袋をはじめとする緩い “なんでも掲示板” とは違います。技術系掲示板のほうが「本当にそのツールを開発・メンテナンスしている人達」が出入りしていますので、“なんでも掲示板” より役に立つ答えが返ってくる可能性が高いです。しかし、技術系コミュニティではそれぞれのコミュニティごとに雰囲気があります。「ここにくるということは、これくらいのことは前提として知っているべき」という考えの参加者が大勢を占めている場合も多いのが実情です。
そこで、まずは過去にそこで質問された質問を検索し、雰囲気をつかんでしまいましょう。郷に入っては郷に従えです。中には質問が初歩的すぎて回答すらついていない悪い例もあるでしょうし、質問の内容をもとにツールの改善がなされて洗練されていった良い例も見つかるでしょう。これをもとに、どうすれば回答がつきやすいかというコツも盗んでしまいましょう。運が良ければ過去ログを検索して読むだけで自分の疑問が解消するかもしれませんので、一度試してみる価値はあります。
一つ肝に銘じてほしいことがあります。よく誤解されますが、技術系コミュニティでは正確には「質問者」や「回答者」といった概念は存在しません。皆が参加者であり、質問することも回答することもある議論の場として掲示板が設けられていることがほとんどです。そこに質問するからには、自分の質問とそれに対する回答も後から来た人に読まれることを意識しなければなりません。そう考えると、おのずと質問のしかたもわかってくるのではないでしょうか。後から来た人が自分の質問とその回答を見て「ああ、前にあるこの人の質問と自分は同じ疑問を持っていた！ これを読んだら解決した！」というように質問せずに解決することだって十分あり得ます。掲示板の過去ログはすべて、そのようなデータベースとしての役割も担っています。自分の質問も回答もデータベースになる、そしてそれがもしかすると後から来た人の役に立つかもしれない。そういう意識を持つようになると、もうそれはデータベース構築というかたちでコミュニティに自分も貢献しているといっても過言ではないと思います。
良いレポートへの道 (2) ：情報不足は禁物！
私も TeX Forum に参加していますので、ときどき LaTeX ユーザからの質問に答えます。極端な例として、以下のような質問を考えます。
TeX をインストールしたいのですが、うまくいきません。教えてください。
TeX で画像を貼りたいのですが、うまくいきません。教えてください。
これでは誰も答えられません。
まず、OS によってインストール方法は違います。隣にいる人に「ちょっと教えて」と聞いているのと Web 上の質問掲示板とでは状況が異なります。あなたがどんなコンピュータを持っているのか、あなたのコンピュータスキルがどの程度なのか、それは Web を見ている回答者には分かりません（上のような情報不足な質問しかしないような人は初心者だろうとすぐにわかりますが）。
さらに、「うまくいきません」とは何でしょう？ あなたが何を期待していてどうなってがっかりしているのか、回答者に全く伝わりませんね。はたまた、あなたが期待しているのは本来の正解ではないかもしれませんし、“うまくいっていない” と思っていたら実はそれは成功だったという勘違いもあるかもしれません。
もし本当に答えてほしいのならば
TeX をインストールしようと思って、このサイト [URL] を参考にしてインストールを試みました。OS は Windows 8.1 です。手順に従って…まで進めることができましたが、インストールの途中で…というエラーが出て止まってしまいました。対処法を教えてください
以下に示すような LaTeX ソース（ここでは略すが、勝手に省略せずに全部*1貼る！）を作り、ptex2pdf で PDF に画像を挿入したいのですが、DVI ファイルはできますが PDF ファイルができません。DVI を dviout で開いてみると画像が表示されています。対処法を教えてください。
のように、詳しく状況を説明しましょう。「うまくいきません」は掲示板で本当によく見かけます。「うまくいきません」という発言をしそうになったら常に「何をどうしたら、何がどうなってほしいのに、どうなってしまった」という形式で言い換えるように心掛けましょう。
良いレポートへの道 (3) ：原因を分離する！
たとえば「日本語を含んだ論文を TeXworks を使って ptex2pdf で処理したいのだが、日本語が出ない」という場合を考えます。この原因はどこにあるのでしょうか？
という可能性がまず考えられます。原因を特定したければ、まずは論文よりも簡単な「あいうえお」とだけ書いた LaTeX ソースを TeXworks で処理してみて、それでも日本語を処理できないのかどうか確認します。ここで成功したならば、論文のソースを書き間違えているのでしょうし、ここでも失敗すれば TeXworks の設定か TeX のインストールを疑うことができ、原因を分離できたことになります。さらに分離するにはターミナルからコマンドで pLaTeX と dvipdfmx を実行し、成功すれば TeXworks の設定が悪い・失敗すれば TeX が正常にインストールされていないと判断します。
このように、複数のソフトウェアの組み合わせ（上の例では TeX と TeXworks）で起きているトラブルは、どれか一つを変えてみる・あるいは使わないようにすると原因特定できます。このように原因を分離すると、質問する前に検索しようと思ったときにも非常に便利です。
ときには “よくわからないけどこうすると解消する” という場合もありますが、多くの場合「原因が分からないと解決法もわからない」ものです。いろいろなツールが絡み合って同時に動くような場合、特に原因が見えづらくなりがちですが、ひとつひとつ「ここは大丈夫」と確認していけば、その絡み合いがほどけて問題が小さくなっていきます。Web 上の解決法の説明、それも “よくわからないけどこうすると解消する” ではなく「よく分かっている人による的確な解決法」の説明は、原因と対策を説明している場合が多いです。それを検索でヒットさせるためには、原因を特定しなければ始まりません。原因が分からないままナントナク解決している方法は、いつかボロが出ます。ときには、それがバッドノウハウであることもあります。適切な正攻法で解決したいと思うならば、多少時間はかかっても原因の特定のために努力するのが結局は近道です。
良いレポートへの道 (4) ：原因箇所を極力絞る！
あなたが作成したソースについて期待どおりにならず失敗し、それがなぜかを質問したいとしましょう。そのソースがたとえば100ページにもなる場合、そんなにたくさんのソースが必要でしょうか？ 1ページだけのソースで同じエラーが出るのであればそれで十分ですよね。
もしそのソースの一部を削除しても同じ現象が起きるならば、それはまだ残っている部分のソースに失敗の原因があることを意味します。さらに削除を繰り返し、「これ以上減らすともうエラーは起きない！」というところまで削ってみましょう。すると、原因箇所が特定できます。これは当然ですが、非常に大事なことです。これを「現象を再現する最小ソース」と呼ぶことが多いです。
このように「期待したとおりにならず失敗する」という現象を再現できる最小ソースを掲示板に貼れば、もともとのソース全部を貼るより効率的なのは言うまでもありません。長〜いソースを全部読むのは回答者にとっても面倒ですし、初めに述べたとおりデータベースとしても読みづらく無駄が多いといえます。分かる範囲でできるだけ切り詰めて、最小のソースを示しましょう。
これはたとえば、いま作成しているソースが個人情報を含んでいて公開したくない場合にも役に立ちます。こういう場合に「質問できない！」と泣き寝入りするのではなく、「こういうソース以外でも同じ失敗が起こるのだろうか？」と考えることは大事です。個人情報を含まないように似たようなソースを作成して同じ結果を再現できれば、それを元に質問すれば良いわけです。
より優れたレポートのために：原因を一般化・特定する！
先ほど少し触れましたが、「こういうソース以外でも同じ失敗が起こるのだろうか？」を一般化してみましょう。これはかなり高度な気もしますが、もうひとつの例を考えてみます。「猫の写真をとったのでそれをここに貼りたいので、…という手順を踏んだところ、写真が表示されなかった」としましょう。そして (4) までの手順を踏み、原因がどのツールにあるのかまでは分離できたとします。それでも問題が解決しない場合は
- 猫の写真特有に何か問題がある（ファイルが壊れているなど）
- 写真が PNG 形式で、ツールが PNG 形式にそもそも対応していない
- 画像の形式によらず、どんな画像 (JPG, PDF, etc.) でも表示されない
など、いろいろな可能性が考えられます。同じ拡張子の画像にもいろいろなバージョンがあるという可能性もあります。よく知られている PNG を例にしても
- アルファチャネル（透過入りの場合など）の有無
- 解像度の違い（72dpi や 96dpi など）
のように少しずつ違います。どんなファイルの場合に同じ現象が発生するのか、いろいろな例で試してみると原因が分かる場合もあります。この段階までくると、「慣れ」が肝心です。もちろん素人が調べている場合、一般化しようとして本来のものとは原因を取り違えてしまうこともあるでしょう。しかし、それも勉強です。慣れていくほかはありません。
それらしい原因を見つけることができた場合は、報告する際に「もしかすると一般に…が原因なのかもしれません」のように申し添えると良いでしょう。このように仮に一般化したとしても、同時に具体的なソース例を示すことが肝心です。レポートの例としては、「具体的なソース例をあげる→自分なりに原因を調査した経緯を説明→自分なりに考えた原因の示唆」のようなやりかたがあるでしょう。こうしておけば、参加者がすぐに現象を再現してもらえるだけでなく原因調査の労力が大幅に節約でき、さらに仮にあなたの原因一般化が間違っていても誰かが正してくれることでしょう。
このように「一般に…という場合に期待しない結果となる」「その原因はほかではなく…にある」という原因の特定と分離ができている報告は、ほかの参加者にとってありがたいものであると同時に、あとから見る人にとってもありがたいものです。開発者として参加している人にとっては、もしかするとその質問を見て「ツールの動作がよくないので改善すべきだ」と判断して対処してくれるかもしれません。もしそうでなくとも、質問者が努力して原因を突き詰めたところは汲んでくれるはずですので、質問者の使いかたや認識が間違っているならばそれを真摯に指摘してくれることでしょう。このようなレポートが蓄積されていくことが、コミュニティにとっても理想ではないでしょうか*2
実際にレポートするにあたって心に留めるべきこと
さて、5つの観点から「よいレポートとはなにか」を考えてきました。理想は (5) の段階まで進むことですが、そこまでを全ての人に求めようとは思いません。しかし、(1) から (4) は常に心に留めておくべきだと私は思います。もう一度まとめておくと
- 超必須：事前調査でコミュニティの雰囲気をつかむ
- 超必須：情報不足は禁物（「うまくいきません」は厳禁！）
- 必須：的確な対策を知るには原因を分離する
- 必須：原因箇所を極力絞る
- さらに：原因を一般化し特定する
もう一つ、これはよくありがちですが「これはバグ（もしくは不具合）ではないでしょうか？」は良い言い回しとは言えません。バグではなくそれが “意図した仕様” なのかもしれませんし、バグではなく “単純にまだ対応していないだけ” なのかもしれません。直近では OS X 10.11 El Capitan がリリースされた際に「El Capitan では TeX にバグがあって TeX が使えない」という言明が各所で観測されました。サブブログでこの件についてちらっと触れましたが、これは El Capitan での Apple による大幅仕様変更に未対応だっただけ*3で、バグなんかでは決してありません。このような事情を知らずにバグだの不具合だの騒ぐのは失礼にあたるといっても過言ではないでしょう。使っているツールから出てきた結果があなたにとって嬉しくないものだったとして質問したい場合は、せめて「これは意図した挙動でしょうか」とか「こういう場合にも対応していただけないでしょうか」というような表現にすると角が立たないと思います。
そして、レポートしたあと参加者から何かしらの反応があった場合。これは大変ありがたいことです。開発者の方がツールを改良して問題に対処してくださったり、認識の誤りを正してくださったりすることは、他の何を参考にするよりも勉強になるものです。指示されたことを実行し、その実行内容と結果をフィードバックすることは、自然と後の人にも役立つデータベースの一部になっていきます。レポートの前に自分で調査したこと、得た回答から学べること、回答をもとにより詳しく事後調査すること、これらのすべてがあなたの糧になります。手間を惜しまずにひとつひとつ学んでいくと良いでしょう。
最後に：だいじなことは
これはいちばん大切なことですが、常にコミュニティに対する感謝を忘れないようにしましょう。オープンソースのツールを開発している技術系コミュニティは、すべて善意の無償の努力によって成り立っていることが多いです。顔が見えなくても、ユーザであるあなたと同じくメンテナも人間です。大きなツールになればなるほどその安定的な維持開発は手間のかかる作業ですから、開発者・メンテナ・それに協力している技術系コミュニティの存在は重要です。その存在を気に留めておくと、どういう態度が適切なのかおのずと見えてきます。
良いレポートは往々にして、コミュニティにとって・特に開発者にとって嬉しいものだと思います。自分のツールを一方的に提供するだけでなく、レポートが来ることで初めて “自分のツールは使われていて役に立っているのだ” という実感が得られますし、真摯なレポートが返ってくることはもっと改善しようという意欲につながるかもしれません。
この記事を読んだ方は、ぜひあなたに馴染み深い技術系コミュニティで実践してみてください。私の場合も「自分も何かできることはないか」と気負って始めたわけではなく、自然と上のような考えにいたりました。これが正解なのかどうかは全く分かりませんが、特にコードを書いて貢献するわけでなくとも寄与できる「居場所」を見つけることができている気がします。以前に「TeX にかかわるコミュニティ」の特性を私なりに考えたときの記事も参照してください：
*1:よくわからなければ全部貼りましょう。もう少し賢い方法は (4) で詳しく述べますが、わからなければ全部貼るのが手っ取り早いです。
*2:…といいながらも、この(5)についてはどこまで実践するのがよいか悩みどころです。場合によっては間違った方向に議論をすすめかねず、時と場合によるかもしれません。このあたりについてみなさんの忌憚なきご意見をコメント欄にください。
*3:例えば「MacTeX-2014 がインストールする /usr/texbin が El Capitan の rootless で使えない」は、その時点で MacTeX 開発者は rootless になるなんて想定外だったから起きたことです。早急に対策した MacTeX-2015 ではこの問題が解消したというのはそういう事情です。もうひとつの「dvipdfmx にバグがあって El Capitan でヒラギノが使えない」も間違いで、El Capitan についてきたヒラギノは OpenType Collection という知らない形式で、TeX Live 2014 までは未対応だったものを TeX Live 2015 では対応させるために改修を行ったということです。
