Discordはドキュメントではありません
(shkspr.mobi)- Discordはリアルタイムの支援や作業の共有には役立つが、プロジェクトの継続的なドキュメント化を代替するには構造的に不向き
- オープンソースプロジェクトがユーザーの集まる場所でコミュニケーションするのは自然だが、Discordは本質的に一時的な会話に向いたツール
- Watchy開発プラットフォームは、基本設定ガイド以外の情報はDiscordで質問するよう促しており、APIドキュメントがないため、ユーザーはメッセージを自分で掘り返さなければならない
- 検索で質問を見つけても、回答の文脈と関連性を把握しにくく、同じコマンドやオプションが見当違いに解釈されることがある
- よくある質問と回答を一か所に集めなければ、ユーザーは製品を学び使う過程で不要な摩擦に直面し続ける
Discordが助けることと、代替できないこと
- Discordでは問題についてリアルタイムの支援を受けられ、他の人が何を作っているのか、どこで詰まっているのかをすぐに見られる
- 参加のしやすさは、Slack、Matrix、Gitter、IRCのような他のコミュニケーションツールと大きく変わらない水準
- オープンソースプロジェクトが「ユーザーのいる場所へ行く」という原則に従うのも自然
- みんながFacebookにいるのにMySpaceだけに投稿するのは意味がない、というたとえを挙げている
- Discordがオープンソースではない点は多少気になるが、Firefoxで開いても問題なく動作する
- 要点は、Discordが一時的な会話には適していても、ドキュメントの代替にはならないということ
Watchyで露呈したドキュメント化の空白
- Watchy開発プラットフォームを始める過程で、次第に大きなフラストレーションを感じるようになった
- 提供のされ方は「設定のための基本ガイドはここにあり、それ以外はDiscordで聞いてほしい」に近い
- APIドキュメントがない状態で必要な情報を見つけるには、ユーザーが大量のメッセージを自分でスクロールしなければならない
- 情報がDiscordの会話の中にしか残らないと、ドキュメントのように構造化された参照点が失われる
検索では解決できない文脈の問題
- Discord検索は、人々がスレッドを適切に使わない場合、実質的な解決策になりにくい
- 質問は見つけられても、回答を一緒に見つけるのは難しい
- 回答を見つけたとしても、それが現在の質問への答えなのか、別の会話への答えなのか判断しにくい
- 例の会話では、fullscreenコマンドの質問、ディスクフォーマットの質問、
-fフラグの回答が混在しており、回答の対象となる文脈が不明確になる - このような構造では、同じコマンドやオプションがまったく別の意味として読まれかねない
初心者と繰り返し質問が直面する摩擦
- Discordに情報が散在していると、初心者はすでによく出た質問を繰り返すことになる
- 一部の人は、こうした初心者の質問にいら立って反応する
- 繰り返し質問が多いなら、共通の質問と回答を一か所にまとめるほうが、より直接的な解決策
- FAQが包括的なドキュメント化の正しい最終形ではないかもしれないが、最低限の情報整理としては必要
少なくともまとめておくべきドキュメント
- Four-Document Modelに必ず従う必要はない
- このモデルには批判もある
- それでも、よくある質問と回答をまとめておかないのは理解しがたい
- 包括的なドキュメント化をFAQだけで解決することはできないが、FAQすら作らないプロジェクトは、製品公開そのものを再考すべき
1件のコメント
Hacker Newsの意見
スタートアップがサポートまで含め、あらゆるものをDiscordに押し込む流れがありますが、記事で述べられている理由から、ユーザーや顧客にとってはひどい体験になります。
チャンネル構造を把握し、どこに投稿すべきかを探すのに時間がかかりすぎ、すでに解決策が投稿されているか検索するのも困難です。実際に誰が答えてくれるのかも分かりません。スタートアップを運営していて、すべてをDiscordへ移そうとしているなら、真剣に考え直すべきです。
Google検索やヘルプポータル、ドキュメントサイトの探索で見つけられる公開情報を用意しておく代わりに、すでに回答済みである可能性の高い質問を、全員がチャットルームに入ってもう一度尋ねるようにしているわけです。自分たちの仕事も増えます。ヘルプやドキュメントを見ずに質問する人が多いのは分かりますが、セルフサービスサポートで10%でも解決できるなら、そのようなドキュメントを最新の状態に保つ価値はあります。
以前にもHacker Newsで取り上げられた話題です: “Discord is a black hole for information”
https://knockout.chat/thread/33251/1
https://news.ycombinator.com/item?id=30311982
少なくとも私の場合、オーディエンスはとても若く、皆Discordにいたがります。まともなコミュニティメンバーがモデレーションを引き受けると言ってくれれば、実質ほとんど手間なく回ります。私の経験では、Discordはコミュニティ側から先に求められたもので、始めようと言い出したのも私ではありません。他のプラットフォームは私が押しても誰も望みません。なぜうまくいくのかは分かりませんが、とにかくうまくいきます。
音声、映像、テキストに対応し、リアルタイムのやり取り、遅延したやり取り、自動化されたやり取りも可能です。Web、デスクトップ、モバイルにも対応しています。サポート手順や教育を単純化するため、1つのツールに標準化したいと思うのは理解できます。アクセシビリティとユーザビリティを改善できさえすれば、Discordは多くの面で大きな前進になり得ます。チャンネル数を減らし、名前を明確にすることは良い第一歩で、短い歓迎メッセージやヒントも役立つでしょう。
デフォルトの通知設定が完全におかしく、すべてが常に未読で、すべてが重要で、あちこちに赤いバッジが付きます。新しい「サーバー」に入るたびに、まず右クリックして「@everyoneおよび@hereを抑制」「ロールメンションを抑制」を選ばなければなりません。それでも@everyone、@here、@roleのメッセージは、個人的にメンションされたかのように黄色で強調表示されます。ブロードキャストメンションは乱用されるに決まっている機能なので、そもそも作られるべきではありませんでした。
メッセージ入力欄も、妙に賢そうに振る舞う一方で、同時にかなり間抜けです。macOS標準のテキスト置換を壊しましたし、記憶では、メッセージが特定の文字で始まると一部の文字を食ってしまいます。なのに@usernameを直接入力して、表示されるオートコンプリートを選ばないとメンションが機能しません。
リアクション絵文字を追加するUIも、ばかばかしいほどひどいです。最近使った絵文字を表示した後、購読していなければ使うこともできない全サーバーのカスタム絵文字を延々と見せられ、その後でようやくUnicode絵文字が出てきます。
有料サブスクリプションを宣伝するポップアップ、バナー、ツールチップも非常に邪魔です。「新着情報」ポップアップも同じです。何年も無料プランで使っていてお金を払っていないなら、もう転換可能性は低いと見て、有料顧客に変えられるという期待で目障りなアップセルを続けるのはやめてほしいです。
ファイルもあまりに頻繁に「too powerful」だとしてブロックされるのに、サーバー側が望む方式で圧縮させる選択肢もありません。画像や動画をビット単位で完全に送る必要はめったにないにもかかわらずです。いつか次のプロジェクトとして、現代的なマルチプロトコルのデスクトップメッセンジャーを作るつもりで、Discordは対応サービス一覧の一番上に置く予定です。
特定の話題に対するHNの即時反応が、だんだん疲れるものになっています。
今コメントしている相当数の人は、記事が何についてのものかも読まず、昔のメーリングリストや作りかけのドキュメントへの郷愁を吐露したいだけに見えます。そうしたドキュメントは、よくてもコード例が1つあり、平均的には結局読むべきソースコードの「目次」程度のものでした。個人的には、こうしたプロジェクトがDiscord以外にBBSも持ってくれればいいと思いますが、自分が関心のあるものを作っている人たちとただ話し、その過程で友人になるのは本当に良いものです。
Watchyの場合、ドキュメントは良い出発点でした: https://watchy.sqfmi.com/docs/getting-started
アーキテクチャ図があり、よくあるユースケースのコード例もいくつかあり、このプロジェクトが扱う範囲の広い「冒険型」プロジェクトであることもかなりよく伝えています。いつか他の人が作った記事やプロジェクトへのリンクを追加できるかもしれませんが、そうした資料が多いかは分かりません。かなりニッチな製品です。
ここには多くの人を刺激するテーマがいくつかあり、実際の投稿が何であれ、記事も読まずにあらかじめ抱いていたコメントを投稿します。誰かが「discordsucks」のような使い捨てアカウントを作ってコメントしているだけでも、それは十分に表れています。
そのうえ、それらは「サーバー」ではなくチャンネルです。
私たちも https://www.answeroverflow.com/ を使って、Discord の内容を Web にミラーリングし始めた
自分たちで似たようなものを作ることもできるが、AnswerOverflow にはよい機能があり、同意に関する問題もうまく扱ってくれる。Discord を新たに始めるなら、今すぐミラーリングしないとしても、コンテンツを別の場所にミラーリングできることを最初から明記しておくことを強く勧める。後からやろうとするとずっと難しくなる
よりよい解決策は Discord を使わないことだろうが、代替手段への抵抗や仲間からの反対、コミュニティが分散するかもしれないという不安のため、私たちにはこれが最善だった。そもそも Discord を使わないのが最善かもしれないが、少なくとも一部のコミュニティでは、慣れているという利点がある。「ちゃんとした」ドキュメントも維持しているが、すべてを載せるのは難しく、Discord には他の場所に記録されていない価値ある内容が含まれている
基本のコミュニケーションは XMPP MUC、Matrix Spaces、IRC のようなオープンなもの、または Zulip、Mattermost のような場所に置く形だ。今週流行のチャットツールが変わっても、本拠地が、制裁や新しい有料の壁でサービスを切れる巨大企業によって運営されることはなくなる
前の会社でサポート用に Discord を使っていたが、素晴らしかった
コミュニティを初期に築くには時間がかかるが、いったんできれば大きな資産になる。最大の利点は、リアルタイムのユーザーフィードバック、ユーザー維持、ユーザー同士の協力、コミュニティベースの支援だ。Discord は対話型なので、プロダクトへのフィードバックを受けたら、具体的にどんな問題に直面しているのかを素早く話し合い、解決策を提案して反応を見ることができる。ユーザーがプロダクト開発者に即座にアクセスできれば、自分の意見が有用に使われていると感じ、継続率も上がる。コミュニティが十分に大きくなると、ユーザーが一緒に改善案をブレインストーミングしたり、新規ユーザーを助けたりして、開発者がサポートに費やす時間を減らしてくれる
個人的には「インデックスされない」という批判は少し滑稽だと思う。難解なエラーを検索してメーリングリストにたどり着いたことが、どれほど頻繁にあるだろうか。たいていインデックスされたメールには回答がなく、回答があっても問題を解決できないことが多い。会話履歴を掘り返すのは効率的なドキュメント化の手段ではない。私たちはコミュニティからのフィードバックを、ドキュメントで欠けている部分を把握するシグナルとして使い、それに合わせてドキュメントを更新している。今週ユーザー 10 人が機能 X について尋ねたなら、ドキュメントを更新すべきという意味だ
今はスレッドがあるとはいえ、全員が使わなければならない。同じ質問をした人を見つけたのに答えがなければ、本当に答えがないのか、1000 件のメッセージの下でスレッド外に回答されたのか分からない。スレッド化なしでは惨事だ
難解なエラーを検索してメーリングリストにたどり着いたことは多いが、フォーラムのほうがよかった。Discord や Slack ではほとんど回答を得られないか、得られても良い回答ではなかった。質問が上に流れていくと誰にも見られず、誰かが答えても問題を理解していない熱心な初心者であることが多い
以前はフォーラムによく投稿していて、よく検証された再現例で問題を正確に示していた。また「質問を 1 つしたら回答を 1 つする」式に、最初の 1〜2 ページの未回答質問を見て回り、分かるものがあれば答えを残していた
ほぼすべての Discord や Slack の「サポート」チャンネルはひどかった。企業がユーザーを無視する方向へ期待値をずらし、サポートを減らすやり方だ。Drone（CI）も最近そうしており、Slack チャンネルはユーザーの質問で埋まっていた
Discord などが人気な本当の理由は 労力コストの低さ だと思う。完成した例を持ってくることは期待されず、会話なのだから半分できた質問を投げておき、誰かが誘導して手を引いてくれるのを待てばよい。その代償は、絵文字やミームだらけの場ではなく、労力を必要とするコミュニティに参加したい人たちを失うことだ
Web 自体が 検索するのがほぼ不可能な空間 になってしまった。検索エンジン最適化スパム、Google 検索の品質低下、あらゆるものが囲い込みの中に入っていく現象、LLM に対抗して API 価格を上げ、データを抱え込む流れのためだ
一般に、検索可能な Web が死につつあることが Discord への移行を後押ししていると思う。個々の開発者のせいというより、彼らにとっては言われている通り純利益が大きい。必要なのは「ozempic web」だ。2023 年の規模は保ちつつ、より軽く、インデックス可能で、囲い込みがなく、無駄な水増しや注意を引くタイプの収益化が少ない Web であるべきだ。それまではプレイヤーをどれだけ責めても、ゲーム自体が歪んだ状態だ
しかしそれは 選択バイアス だ。オーナーが参加した会話は当然うまくいく。では他の会話はどうなるのか。誰も答えなかった質問が 3 時間後に別の会話に埋もれれば、会社はその質問を見ない。会社は見ていないものを見ることはできず、そのため選択バイアスが生じる
Discord は情報をそうしたオープンな場所から奪っていく。時にはそうした回答を通じてプロジェクトを発見することもある。ただし私はプロプライエタリコードのスタートアップより FLOSS に関心があるので、主な顧客フォーカスが違う問題なのかもしれない
第一に、Discord をドキュメント化プロセスに統合することに成功している。X についてフィードバックを受けたら、ドキュメントを更新して X を扱う。一方で Eden は、多くのプロジェクトが Discord で X に回答した後、ドキュメントを更新しないと言っている
第二に、チームが Discord のメッセージに素早く回答している。多くのチームはだらだら先延ばしにするか、まったく応答しない
チャットはドキュメントではない
行き詰まる箇所が出てくると、まず実装をざっと眺めますが、慣れていないコードベースなのでうまくいきません。ドキュメントを確認すると「Discordコミュニティに参加してください」というリンクしかありません。そこでDiscordを開き、アップデートをインストールし、カスタムメールベースの2要素認証を行い、変更された規約に同意し、Nitroのバナーを閉じ、サーバールールに同意してから #general に入ります。できるだけ文脈を盛り込んで質問を投稿しますが、返事はありません。結局デバッガを起動し、ライブラリやフレームワークを1行ずつ追いながら何が起きているのかを調べます。変更可能なコピーを作ってロギングを追加し、いくつか修正を試した末、数時間後にXがYをサポートしていないこと、あるいは値をBase 47やLatin 1でエンコードして渡す必要があることを突き止めます。そして3日後の午前1時に、私が参加する2週間前にDiscordで行われていた会話を見ろという、突き放すような返事を受け取ります
チャットは、問題を自力で把握し、ユーザー同士で互いにサポートしなければならない負担を、ユーザーに大きく押し付けます。特に非同期作業の世界では、ドキュメントの代替にはなりません。非同期に回答できるから非同期作業に向いていると思いがちですが、非同期に詰まりを解消できるわけではないので、そうではありません
過去12年のうち約8年、Djangoで仕事をしてきましたが、Djangoのコードにデバッガを使ったのは、セキュリティ脆弱性を発見し、非常に低レベルの詳細を確実にする必要があったときくらいがほぼ唯一でした。一方、ドキュメントの代わりにDiscordを勧めるプロジェクトで、趣味プロジェクトを1か月のうち約5日やっただけなのに、何が起きているのかを突き止めるためにデバッガを3回も使わなければなりませんでした
ここには本当に役立つ、文化的・プロセス的な解決策があります。Discordでの質問をドキュメント更新へ丁寧に変換することです
そうすればDiscordは、プロジェクトのドキュメント品質を高める強力な加速装置になり得ます。ただし、それだけの規律が必要です
自分の仕事をしなければならないのに、一日中Slack、Discord、Mattermostを監視しなければならないなら、自分の仕事はできません。自分の仕事がサポート業務なら別です。開発者たちは概して素朴で、自己主張が強く、人を満足させようとするため、ソフトウェア開発が別のビジネス領域であるサポートまで引き受けてしまう、また別の例です。アジャイルのときはプロジェクト管理を背負い込み、DevOpsのときはシステム管理を背負い込みました。状況によっては違うかもしれません
もう誰かが実装していそうですが、最後に探したときは何も見つかりませんでした
製品ユーザーとして、見ず知らずの人たちのコミュニティに入り、非生産的な会話に巻き込まれたくありません
ほぼ同期的なチャットを更新し続けたいわけでもなく、1日見逃しただけで重要な情報を逃したくもありません。企業には私の時間と注意を尊重してほしいです
Discordの検索は驚くほどひどいです。ユーザーは何年も不満を言い続けていますが、改善されていません
これだけでもドキュメントとして使う資格はありません
ユーザーがサーバーを離れると、その人が投稿した内容を特定して検索できなくなります。ユーザーがまだサーバーにいても、Discord検索が現在の全ユーザーを常に把握しているようには見えず、その人の投稿を見つけるのが難しいことがあります。大量の検索結果を検索して、最初のページ、つまり最も古い結果に戻ろうとすると壊れます。例えば、あるサーバーでは自分の最初のメッセージにジャンプできません。特定のスレッド内を検索することもできません。テキスト検索の方式自体も以前は気になっていましたが、今は何が問題だったのか良い例を見つけられません
こうした会社では、エンゲージメント、つまり時間の浪費が望ましい品質と見なされる傾向があります
同じ理由でSlackもドキュメントではありません
今、会社全体のドキュメント化を改善する仕事をしています。私たちは古いスタートアップで、市場投入まで非常に長くかかる分野にいますが、前四半期には古いコードに関する質問に答えるために数週間を費やしたプロジェクトを2つ率いました。元の作者がすでに会社を去っていてドキュメントがまったくないこともあれば、元の作者がまだ会社にいるのに、そのコードを書いた事実そのものを文字どおり覚えておらず、やはりドキュメントがないこともありました。そのたびに、人々はすべてを説明するSlackの会話がどこかにあると言います。いいえ、ありません。すべてのプロジェクトとアプリケーションには、事前には設計ドキュメントが、事後にはユーザーマニュアルが必要であり、実際に保守されなければなりません
より広いコミュニティが Discord に妙なほど熱狂しているのが不可解
他の人も言っているように、本質的にはマルチメディア付きの IRC。なぜあれほど熱心に宣伝するのだろうか？ 「Discord でサポートを受ける」という非常に議論の多いアイデアを受け入れるとしても、製品自体は特別ではない。既存の類似製品より少し良くなっただけ。今後ユーザーデータがどう使われるかについての非常に現実的な懸念はまた別の話
そして多くのユーザーは IRC を使ったことがない。サービスと同じ名前のアプリがある点も大きい。だから Instagram や TikTok のように一つの「もの」になる。reddit アプリと reddit のサービス・サイトが別物だということを考えたことのない人がどれほど多いかを見ると、かなり驚く。より広い IT コミュニティも依然として小さなニッチに近く、私たちはそのことをよく忘れる
Slack を除けば、Discord は消費者向けのブラウザベースのチャット・音声アプリの中で、次に品質の高い製品を作った。よく設計され、安定していて、ほとんどはシンプルなユーザーインターフェースを備えている
IRC や、よく挙げられる多くの代替案は、マルチメディアどころか純粋なテキストチャットだけでも、その最初の段階でつまずいていることが多い。それを理解した競合は、実装で失敗したか、到着が遅すぎた。プライバシー上の懸念はユーザーの優先順位では低すぎるため、Discord の先行者利益を崩す可能性は小さい
それだけでも十分。だが多くの面で IRC よりはるかに優れてもいる。もちろん Libera 用の IRC バウンサーを「シェルアカウント」や常時起動の AWS マイクロインスタンスで自分で動かすことはできるが、よほどのギーク以外で誰がそんなことをしたいだろうか。それでも新しいチャンネルに入ったときに過去メッセージを見ることはできず、ログボットやアーカイブページがあっても不格好だ。ネットワークごとに NickServ の儀式を行うことも忘れてはいけない。そして今ではほとんどのユーザーが一般的なコミュニケーション文化として期待する、優れたマルチメディアもない
そこに、まともな UI、送信者が受信者に何が表示されるかを正確に把握できるリンクプレビュー、Markdown 風のメッセージ書式、返信を結び付けるのに十分なメタデータ、チャンネルをスパム化しない簡潔な絵文字リアクション、追加設定なしでうまく動く音声・ビデオ会議まで加わる。検索と検索 UI は別として、代替案の中では Zulip くらいを除けば UI も良い
以前は IRC を毎日使い、アーカイブ用バウンサーを運用し、コミュニティチャンネルを管理したこともあったが、今ではもう気にしていない。しばらく忙しく体調も悪かった間に、登録していた NickServ ユーザー名が失効してチャンネル管理まで壊れ、それでやる気を削がれた面もある。皆が Freenode から Libera へ去ったとき、そのまま IRC の利用をやめた
同時に、プロジェクトが有用なドキュメントを作り続けておきながら、事実上失ってしまう形で Discord を使っていることへの批判には強く同意する。Discord が理解できるネットワーク効果を持つ、高品質で洗練された製品を作ったことは認めるべきだ。だが、プロジェクトがチャンネルを公開アーカイブして検索可能にするのが難しい点は残念だし、オープンなネットワークでもオープンソース製品でもない点も残念だ。検索と検索 UI がひどいことも同様
私が見ている Discord 利用プロジェクト、特に商用プロジェクトまで含めて、その多くがオープンソースであることを考えると、Discord が何らかの形でネットワークを開かない限り、Matrix がいつか代替になる可能性はまだある。ただし既存プロジェクトはチャット履歴とユーザーを移行できず、新規プロジェクトはユーザーがすでにいる場所、つまり Discord、Slack、Telegram のようなネットワークでユーザーに会う必要があるため、摩擦は大きい