ドキュメントチームがページ上で直接質問することで、適切なページを修正した方法

あるオープンソースプロジェクトには、優れたドキュメントと現実的な問題がありました。それは、インストールガイドが微妙に間違っているということです。2つのリリース前に手順が変更されたため、今では新規ユーザーが同じポイントでつまずいてしまいます。人々はそれに気づいており、ソーシャルメディアでの不満や、コミュニティチャットでのいくつかの混乱した質問がありますが、メンテナーはそれに対して何も行動を起こすことができません。なぜなら、どの苦情も**どのページ**であるかを述べていないからです。「ドキュメントが古くなっている」というのは感想であり、バグレポートではありません。そのため、間違った手順が何ヶ月も放置され、使い始めようとするすべての新しいユーザーを静かに遠ざけています。 ドキュメントの成否は、次のループにかかっています。読者が混乱を招く箇所や間違った記述に行き当たり、メンテナーに正確な場所を伝え、メンテナーがそれを修正します。「正確な場所」が欠けると、ループ全体が行き詰まります。 ## 問題: 場所のないフィードバックはノイズである 読者は喜んで協力してくれます。ページがわかりにくいと快く教えてくれるでしょう。しかし、彼らがしないのは、その協力を実行可能なものにするために必要な発掘作業です。URLをコピーし、適切な連絡窓口を見つけ、問題を説明し、どのセクションやどのバージョンであるかをメモするといった作業です。これは、ツールの使い方を学ぼうとしている人にとって、ドキュメントを監査しているわけではないのに多すぎる手順です。 そのため、届いたフィードバックからは、それを有用なものにする唯一の要素、つまり「場所」が抜け落ちています。「APIドキュメントが間違っている」という報告を読んだメンテナーは、何百ものページを抱えており、どこを探せばよいのか見当もつきません。GitHubのissueは役立ちますが、カジュアルな読者にアカウントを作成し、issueのテンプレートを理解し、ドキュメントから完全にコンテキストを切り替えることを求めます。この摩擦が、通りすがりのフィードバックのほとんどを除外してしまいます。しかし、このフィードバックこそが、小さくても影響の大きいエラーを捉えるものなのです。 その結果、奇妙な不均衡が生じます。多くの読者が問題に気づいているにもかかわらず、修正可能な形で報告されることはほとんどありません。 ## 解決策: ページごとの「問題を報告する」リンク すべてのドキュメントページのフッターに、小さな**このページの問題を報告する**リンクを配置します。これは `mailto:` リンクであり、その仕掛けは、現在のページのパスを件名と本文に事前入力することです。読者がクリックすると、場所がすでにキャプチャされた状態でメールが開き、あとは何が間違っていたかを追加するだけです。 ドキュメントは通常、テンプレートまたは静的サイトジェネレーターから構築されるため、パスを自動的に注入することができます。テンプレート化されたサイトでは、ページ変数をリンクに直接挿入します: ```html <a href="mailto:[email protected]?subject=Docs issue: {{page.path}}&body=Page: {{page.path}}%0A%0AWhat is wrong or confusing:%0AWhat would make it clearer:"> このページの問題を報告する </a> ``` または、テンプレートなしでどのページでも機能するように、スクリプトの1行で設定します: ```html <a id="docs-issue" href="#">このページの問題を報告する</a> <script> const a = document.getElementById('docs-issue'); const path = location.pathname; const body = 'Page: ' + path + '\n\nWhat is wrong or confusing:\nWhat would make it clearer:'; a.href = 'mailto:[email protected]' + '?subject=' + encodeURIComponent('Docs issue: ' + path) + '&body=' + encodeURIComponent(body); </script> ``` このサイトのジェネレーターはエンコードされたリンクを生成し、スクリプトは実際のパスに置き換えるだけです。これで、すべてのレポートの件名に正確なページ名が記載され、メンテナーはソースファイルに直接ジャンプできるようになります。 ## なぜこの用途ではページ上での報告が課題管理システムより優れているのか 課題管理システム（issue tracker）は修正を行うための適切な場所ですが、フィードバックの入り口としては不十分です。アカウント、コンテキストの切り替え、プロセスへの精通が求められ、コードサンプルのタイプミスにたまたま気づいたようなカジュアルな読者を遠ざける障壁となります。`mailto:`リンクは、混乱が実際に発生する場所、つまりページ上で、1回のクリックで、アカウントなしで読者に対応します。課題管理システムまでは決して辿り着かないであろう、小さな修正のロングテールを捉えることができます。 この2つはうまく連携します。レポートは、ページが事前にタグ付けされた状態でメールで届きます。メンテナーはそれらをトリアージし、追跡する価値のあるものについてのみ課題管理システムでissueを開きます。入り口ではメールの低摩擦を、出口では課題管理システムの厳密さを得ることができます。 ## セットアップ方法 1. メンテナーが監視する `docs@` などのドキュメント用受信トレイを選択します。 2. ジェネレーターで、宛先、'Docs issue: [ページパス]' という件名、そして何が間違っていて何が役立つかを促す本文を設定します。 3. ページテンプレートのフッターにリンクを追加し、ジェネレーターのページ変数または上記の小さなスクリプトを使用してパスを挿入します。 4. 受信したメールを 'Docs issue:' の件名タグでルーティングし、レポートが1か所に集まるようにします。 5. ループを閉じる: 報告されたページを修正したら、読者への1行の返信がバグレポートを好意に変えます。 ## これによって節約できるもの 1つ目の節約は、**問題の特定に費やされるメンテナーの時間**です。すべてのレポートでページが指定されていれば、探偵作業をスキップして直接修正に取り掛かることができます。かつては対応不可能だった「どこかで何かが間違っている」というレポートが、2分間の編集作業に変わります。 2つ目は、**行き詰まるユーザーの減少**です。ドキュメントのエラーは蓄積します。間違ったインストール手順は1回失敗するだけではなく、誰かが修正するまで新規ユーザー全員が失敗します。「読者が気づく」から「メンテナーが正確な場所を知る」までの時間を短縮することは、悪い記述によって遠ざけられる人がはるかに少なくなることを意味します。普及によって成長するツールにおいて、新規ユーザーのブロックを解除することは成長に直結します。 3つ目は、**フィードバックの量と率直さ**です。報告には1クリックしかかからず、アカウントも不要なため、課題管理システムでissueを開かないような読者を含め、より多くの読者が報告してくれます。信頼を損なうような小さくて恥ずかしいエラーについて知ることができ、それらがまだ重要性を持つうちに耳にすることができます。 ## さらに良くするために - パスとともに**ドキュメントのバージョンまたはコミット**を自動入力することで、レポートが最近の書き換えより前のものであるかどうかを判断できます。 - ドキュメントの**404ページ**にリンクを追加します。不足しているページ自体が有用なシグナルとなります。 - ボットが何千もの公開ページから収集しないように、アドレスを**難読化**して保持します。 - デフォルトのメールアプリを持っていない読者のために、プレーンなアドレスや課題管理システムへのリンクなど、目に見えるフォールバックを提供します。 ## 重要なポイント - 場所のないドキュメントのフィードバックはノイズです。読者が場所を添付する作業をすることはめったにありません。 - ページごとの「問題を報告する」`mailto:`リンクは正確なパスを事前入力するため、すべてのレポートが実行可能になります。 - ページ上のメールは課題管理システムが除外してしまうカジュアルな修正を捉え、その後、実際の修正のために課題管理システムにフィードします。 - これにより、メンテナーの時間を節約し、新規ユーザーのブロックをより迅速に解除し、静かに信頼を損なう小さなエラーを表面化させます。 [ジェネレーター](/#generator)で独自のドキュメントフィードバックリンクを作成するか、以下のセットアップをコピーしてください。