Photo by Markus Winkler on Unsplash
はじめに
こんにちは、TIGの岸本卓也です。 春の入門連載2022 の4日目です。
業務を進める上では日々多くの技術情報を調べる必要がありますが、無策に調べると時間を浪費したりイマイチな解決策を採用してしまう可能性があります。そこで、本稿では普段私がやっている方法を中心に、調べる上でのポイントを紹介します。
調べる方法として、自分で調べる方法と人に聞く方法があると思いますので、それぞれの場合のポイントを紹介し、最後に調べる上で便利なツールを紹介します。
自分で調べる場合のポイント
自分で調べる場合は以下の点が大切です。
- 自力解決に制限時間を設け、それまでに解決できなければ上長に相談したり人に聞くといった別の方法に切り替える
初めてチャレンジすることは分からないことが多いため、全て自分で調べていてはタスクに割り当てられた時間では足りません。課題によってはそもそも自力解決が不可能なこともあります。業務プロジェクトは期限が決まっているので、スケジュールを優先して適宜手段を切り替えていく必要があります。 - 公式情報を当たる
昨今は多数の情報を簡単に入手できますがその質は様々なため、適切な情報を選び取る必要があります。品質が高く信頼性に足る情報源としては公式情報が一番なため公式情報は必ず調べます。 - 解決の選択肢を1個に絞らない
課題の解決方法は複数あることが多いです。したがって最初に見つけた方法をそのまま採用するのではなく、複数の方法を調査、比較、検討して個別事情に適した方法を選択します。
前述の通り公式情報が最も信頼できますが非公式の情報も参考になることが多いです。そこで、以下では公式/非公式それぞれの情報の使い方を紹介します。
公式情報
製品や規格のオーナー自身が公開しているまたはオーナーが認めたコミュニティなどの第三者が公開している情報や、広く認められた団体に登録された情報が公式情報にあたります。公式情報は最も信頼できる情報源のため、常に公式情報は調べるようにすると良いです。
代表的な公式情報には以下のものがあります。
- 公式の原文情報
大抵は英語で記述されています。製品マニュアル、ブログ、課題追跡システム、規格・規約 (RFC) などがあります。使い方や仕様を調べる場合はマニュアルや規格・規約を、エラーや課題を調べる場合は製品のGitHub issuesを調べると良いです。 - 公式の翻訳情報
日本でもよく使われている場合は、製品マニュアルやブログの公式日本語翻訳版が公開されていることがあります。翻訳情報は以下に注意して参考にします。- 時々情報が古いことがあるため、公開日、更新日が古かったり、違和感がある場合は原文を参照します。
- 不自然な日本語のある翻訳情報の場合は機械翻訳の可能性があります。機械翻訳は理解しにくい日本語になっていることや、稀に原文と真逆の意味に翻訳されてしまっていることがあります。読みにくい場合や説明に違和感がある場合は原文を参照します。
- 製品サポート
有償サポートやコミュニティによるサポートが公式に提供されていることがあります。プロプライエタリな製品について調べる場合は公開情報が少ないため積極的に活用する必要があります。調べたいことの期日感や難易度に応じて活用すると良いです。 - ソース
プログラムの動きや事実を把握するには最も正確な情報源です。調べたいことの期日感や必要性に応じて調べると良いです。
なお、製品マニュアルやソースは製品バージョン別の文書を公開していることが多いです。そういった情報は調査したい内容に一致するバージョンの文書を参照することが大切です。
非公式情報
先人が残してくれた多種多様な非公式情報も参考になることがよくあります。しかし、一定の品質が担保される公式情報に対して非公式情報の信頼性はまちまちなため、以下のような工夫をして参考にします。
- 複数の情報を組み合わせる。
- 情報源の信頼性を見極める。
- 公開日、更新日を確認し、古過ぎる情報は避ける。
代表的な非公式情報には以下のものがあります。
- 非公式の翻訳情報
公式原文情報の非公式翻訳であれば内容の信頼性はある程度期待できますが、情報の鮮度は公式の翻訳情報以上に注意が必要です。 - 法人の技術サイトやブログ
当ブログのように会社の看板を掲げている情報源はある程度品質担保された情報になっていると期待できます。 - 技術系Q&Aサイト
Stack Exchangeネットワーク (代表的な物はStack Overflow, Super Userなど) やteratailといったQ&Aサイトはコメント機能や評価機能があることが多く、信憑性のある情報を見つけやすいです。ただし、間違った回答や古い情報が高評価になっていることもあるため裏取りが必要です。 - 個人執筆の記事
情報が古くなりがちだったり、環境依存な解決策が記述されていることがあるため、注意深く検証と裏取りが必要です。 - ユーザーコミュニティ
物によってはユーザーが集まるコミュニティがSlackやDiscordなどにできていることがあります。大抵は英語でのやり取りですが、日本のユーザー会が日本語でやり取りしているチャネルもあるのでログを探したり聞いてみる、という方法もあります。
人に聞く場合のポイント
人に聞く場合は相手が自分と齟齬のない共通認識を持ってもらうことが重要です。そのためには正確な内容を不足なく誤解を生まない表現で伝える必要があります。AWSで「 技術的なお問い合わせに関するガイドライン 」という文書が公開されており、以下の部分はAWSに限らず質問する場合の方法としてとても参考になるため、まずはこれを参考にすると良いです。
- 解決したい課題を明確にする
- 状況を正確に共有する
- 経緯を共有する
このガイドラインに加えて、以下の点に注意すると良いです。
- 情報を絞らない
- エラーメッセージ、ログ、ソースコードなどはパスワードのような機微情報だけマスクして全量共有します。ソースリポジトリ経由で共有する場合は、ブランチ名だけでなくタグ、コミットID、リビジョン番号といったソースのバージョンも伝えると良いです。
- 情報を絞ると質問を受けた方では確実に情報不足を感じます。
- 事実とそれ以外 (自分の考え、仮説など) を混在させない、明確に区別して伝える
これらが混在していると認識齟齬を生みやすいです。 - 試したこと、調べたこと、考えたことは初手で伝えておく
これを試してください→それは既にやっていたけどダメでした、というやり取りは無駄なだけでなく相手の心証を悪くする可能性があります。 - なぜそれを聞きたいのか、背景も伝える
背景を伝えることで、より良い別の方法や考え方を提示してもらえる可能性があります。 - 解決してもしなくても最終的な結果とお礼を伝える
質問した内容とその結果はナレッジや事例としてとても役に立つため、相談相手の糧となったり、同様の課題に直面する他の人の助けとなります。
Web検索におけるTips
最もよく使う調査方法はWeb検索だと思いますので、ここではWeb検索する上でのコツを紹介します。
- 英語で検索する
できれば英語で検索します。特にエラーメッセージを検索する場合は、英文エラーメッセージが出力されるようにして英文で検索した方が良いです。日本語よりも英語の情報の方が圧倒的に多く、適切な情報ににたどり着けるかどうかに大きな差があるためです。ほぼ日本でしか使われていない製品に関する情報のみ日本語で検索します。 - 質の低いページを検索結果から除外する
昨今は高品質な情報が検索結果上位に表示されるとは限らなくなってしまっています。例えば日本語で検索するとStack Overflow英語版を機械翻訳しただけのWebページが出てくることもよくありますが、こういったWebページは、不自然な日本語で読みにくい、検索結果の一部を占めてしまう、悪質なスクリプトが埋め込まれている危険性があるといった問題があると考えています。
そのような低品質なWebページは、指定したドメインは検索結果から排除してくれるブラウザ拡張機能を使ってまとめて消しておくと良いです。 - 検索エンジンの絞り込み機能を使う
検索エンジンで提供されている、サイト内検索、フレーズ検索、除外検索、期間指定といった機能を使って適宜情報を絞り込みます。例えば、製品バージョン別のマニュアルが公開されている場合は特定バージョンのマニュアルだけ検索されるようにサイト内検索を指定したり、エラーメッセージならフレーズ検索したりします。 - ブラウザに検索ショートカットを追加する
ブラウザによってはアドレスバーから直接任意のWebサイト内を検索するショートカットが追加できます (Google Chromeなら サイト内検索のショートカットを追加)。私はよく調べる製品マニュアルや辞書サイトを追加しており、以下のようにすぐに調べられるようにしています。
最後に
本稿では既存の情報を調べるときに私が実践している方法を紹介しました。
課題によっては自力解決は不可能で、ベンダーやステークホルダーを巻き込んで解決策を模索したり想定する解決策に対して公式見解を引き出すといった方法が必要なこともよくあります。視野を広くすると採れる手段が複数見えてくるので、課題解決にあたっては周囲を巻き込んでいくことが大切です。自分で抱え込みすぎないために、最初に書いた制限時間を決めて手段を切り替えていくことを意識すると良いと思います。
春の入門連載2022の次は永井さんの「プロになるJava」読書感想文です。