ハイテク製品のドキュメントが使いにくいのはなぜですか? （ユーザーの視点で）

現在、開発者ツールのドキュメントは使いにくく、YouTube、GitHub の問題、ブログ投稿などの他のソースで解決策を見つける傾向があります。その内容は簡単に後れを取っているか、要点がまったく言及されていない可能性があります。私はこの問題を早急に切り替える必要がある緊急の問題だと考えており、まず 2 つの主要な問題を解決する必要があると考えています。 (ユーザー目線で)

• ドキュメンテーションは貢献するのが難しすぎる
  • ドキュメントは簡単に古くなります。人々は、ドキュメントに貢献するよりもブログ投稿を書く傾向があります。これは、対応するインセンティブがなければ多くの余分な労力が必要になるためです。
• コンテキストがクラスター化されている

  • ドキュメンテーション自体は、他のリソースにほとんど接続されていません。優れたドキュメントを作成するコンテキストはクラスター化されています。

    
    

この記事では、ドキュメンテーションに関して私が問題だと思う 2 つの概念を紹介し、さらにこれら 2 つの問題を解決するための 3 つの考え方に展開したいと思います。

まず、最近閲覧したドキュメントをいくつか思い出して、以下の説明に参加してください。たとえば、現在最も訪問されているドキュメントである Next.js を取り上げたいと思います。まずは「はじめに」のページから。

https://nextjs.org/docs/getting-started

Nextjs のドキュメントは、さまざまな製品に共通する構造を持っており、この構造を「分離リスト構造」と呼びましょう。私がそれらを孤立していると呼ぶ理由は、それらが主に Next.js の背後にいる人々によって維持されているからです (それらはオープンソースですが)。

さらに、このドキュメントの背後にある考え方を「所有者の箇条書き」として締めくくりたいと思います。

オーナーの箇条書き

私がこれを「所有者の箇条書き」と呼ぶ理由は、ドキュメントを生成するプロセスは通常、製品の所有者によって行われるからです。製品の開始時、所有者ほど理解できる人はいません。所有者は、消費者とメンテナーのために適切なドキュメントを維持するのに最適な人物です。

しかし、しばらくすると、製品は多くの愛を受け、コミュニティを構築し始めます。まれなケースやバグのフォローアップがますます難しくなっています。所有者は毎日新しいコミットに追いつき、問題を解決する必要があります。一方で、新しい設計、注意事項を説明し、これらの問題を克服するために新規参入者に情報を提供する必要があります。負荷が大幅に上昇しています。

すべての製品が追いつくわけではなく、コンテンツが後れを取り始め、一部の解決策が他のブログ投稿、StackOverflow の回答、GitHub の問題、またはディスカッションに存在する可能性があります。ユーザーはこれらのソリューションを検索エンジンに接続する必要があり、ドキュメントのソリューションが間違っていることさえあります。

孤立したリスト構造

孤立したリスト構造は、e コマース、汎用 Web サイト、携帯電話、およびドキュメントで非常に一般的です。どこにでもあります。

構造は、所有者がクライアントに最も適していると考える順序で構造のツリーを最初に考え出す必要があるため、「所有者の箇条書き」の考え方から来るほとんど恣意的で独断的です。

孤立したリスト構造は両刃の剣です: 明確にするために、私はこの構造に完全に反対しているわけではありません。一般的な状況では非常に役立ちます.たとえば、最初の探索に適しています。ドキュメントに精通していれば、必要な情報を簡単に見つけることができます。

しかしその反面、構造が固定化されているため、構造が進化しにくく、メンテナーが何かを追加するたびに、所有者が最初からよく考えていないと、適切な場所を見つけるのが困難です。それに加えて、ユーザーはドキュメントを探索する以外に選択肢がありません。ルートは 1 つしかなく、十分ではありません。

力指向グラフのような動的構造を想像してみてください (Obsidian が達成できるものやツリー ダイアグラムなど、公開セクションで多くの例を見つけることができます[^1])。強制指向のグラフやツリー図が孤立したリスト構造よりも優れていると言っているわけではありません。私が望んでいるのは、「リスト方式」ではなく、より「ダイナミックな方式」で考えることを奨励することです。これにより、人々は自分のニーズに最も適したものを選択できるようになります。ツリー ダイアグラムを使用して構造を探索し、力指向グラフを使用してトピック間のつながりを認識することができます。あるいは、これらの問題のいくつかを解決できる新しい構造をゼロから考え出すこともできます。

考え方と構造が相まって、私が問題だと思う問題につながります。

ドキュメンテーションは貢献するのが難しすぎる

「所有者の箇条書き」と「孤立したリスト構造」の恣意的な考え方と相まって、現在のドキュメントは所有者のみが適切に維持できるということです。ドキュメントに貢献する簡単な方法は他にありません。問題は 2 つあります。

まず、「所有者の箇条書き」の考え方に基づいて、作成者は経験の浅い人がドキュメントを台無しにすることを望んでおらず、メンテナーとの連携に多くの時間を費やさないと、ドキュメントのトーンを合わせるのが非常に困難です。

第二に、ユーザーはドキュメントに貢献するインセンティブがありません。人々はあなたの製品を気に入っていますが、ドキュメントの作成やドキュメントのページに対する所有権を認められない場合、インセンティブはありません。

問題を投稿して提案を説明できると主張するかもしれませんが、問題は残ります。貢献するという感覚は非常に同時で、何かを買う感覚と同じです。パラレルワールドを想像してみてください。何かを購入したい場合、なぜその商品を購入したいのか、コミュニティにどのようなメリットがあるのかを説明するために 200 語を書き留める必要があります。

官僚主義で人々がドキュメンテーションに貢献することを制限する必要はありません。ドキュメントの権限を保持し、同時に貢献できる別の構造を考え出す必要があります。

コンテキストがクラスター化されている

優れたドキュメントの素材とは、ドキュメント自体だけでなく、対応するディスカッション、問題、関連するブログ投稿、およびビデオです。これらのマテリアルを「コンテキスト」と呼びます。

最近まで、これらのコンテキストを分散して保存する傾向がありました。通常のオープンソース プロジェクトでは、ディスカッションは GitHub ディスカッションまたは談話フォーラムに保存され、ユース ケースは製品 Web サイトに保存され、問題は GitHub の問題に保存され、セルフホスティング ドキュメント Web サイトは別の場所に保存されます。それに加えて、YouTube や個人のブログ投稿には、コミュニティによって生成されたコンテンツがたくさんあります。

実際には、製品のコンテキストはクラスター化されます。それらは互いに相互接続しません。特定のバグの解決策についての議論があるかもしれませんが、この解決策について言及しているドキュメント セクションには逆方向のリンクはありません。悲しいことに、双方向リンクは現在のインターネットで可能なものではないという現実に対処しなければなりません。

クラスター化されたコンテキストは揮発性です

製品のドキュメントにたどり着いてすぐにドキュメントに解決策がないことがわかり、後日、他の人のブログ投稿で実行可能な解決策を見つけた状況を想像してみてください。

現時点では、現在のドキュメントでは、ブログ投稿で説明されているこの方法で同じ問題を解決できることを他の開発者に思い出させる方法は他にありません。ドキュメントへの参照を追加することはできません。あなたができることは、問題を開く (オープンソースの場合) か、フォーラムでディスカッションを開いて、このソリューションについて人々に思い出させることです。

どのような状況においても有用なソリューションはすべて、現在私たちが手にしている情報の洪水に耐える必要があります。彼らは、検索エンジン以外にアンカー ポイントがない状態で、この戦場に参加する必要があります。

素晴らしいリスト [^2] は良いアイデアです。優れたコンテンツを残す方法を提供しますが、「孤立したリスト構造」と「所有者の箇条書き」の考え方に関して同じ問題があります。

このままの状態なら…

これらの問題の直接的な結果は、「ドキュメンテーション」が時間の経過とともに衰退すると見なされることです。アマゾン ウェブ サービスのドキュメントや Google クラウドのドキュメントなど、技術大手のドキュメントを参照してください。それらはすべて圧倒的で読みにくいものです。

最悪の感情は、ドキュメントや他のどこにも見つからない特定の問題に行き詰まっていることです。ドキュメントの構造が使用する製品の範囲と一致しない場合、この種の状況にさらに直面することになります。

そもそも、これらの問題を克服するために新しい種類の構造を考え出すのは大変なことのように思えるかもしれません。しかし、よく見ると、全体的な問題を 3 つの質問に分けて自問することができます。

• ユーザーにドキュメントへの貢献を促し、ドキュメントの一般的な目的を妨げないようにするにはどうすればよいですか?ドキュメンテーションのために、よりインタラクティブな体験をすることはできますか?ユーザーはページを離れずにドキュメントに直接貢献できますか?

• 外部の検索ソリューションに依存せず、途中ですべてのコンテキストの相互接続性をもたらす、より良い検索エクスペリエンスのためにコンテキストを収集するにはどうすればよいでしょうか?

• ユーザーエクスペリエンスに利益をもたらす可能性のある新しい構造を試して、時間をかけて繰り返したり、ユーザーが自由に選択できるようにする方法は?

  
  

https://twitter.com/EiffelFly

[^1]:黒曜石の公開ページ[^2]: sindresorhus/awesome