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

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

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

    
    

この記事では、ドキュメンテーションに関して私が問題だと思う 2 つの凡路を紹介し、さらにこれら 2 つの問題を解決するための 3 つの考え方に展開したいと思います。まず、近些年閲覧したドキュメントをいくつか思い出して、接下来の説明に缴纳してください。たとえば、現在最も訪問されているドキュメントである Next.js を取り上げたいと思います。まずは「はじめに」のページから。

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

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

オーナーの箇条書き

私がこれを「一切者の箇条書き」と呼ぶ情形は、ドキュメントを转为するプロセスは一般 、製品の一切者によって行われるからです。製品の開始時、一切者ほど领悟できる人はいません。一切者は、消費者とメンテナーのために適切なドキュメントを維持するのに最適な人物角色です。

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

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

孤立したリスト構造

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

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

排斥したリスト構造は両刃の剣です: 明確にするために、私はこの構造に完成に反対しているわけではありません。寻常的な状況では很に役立ちます.たとえば、一开始の生命的进化に適しています。ドキュメントに了解していれば、必要条件な情報を簡単に見つけることができます。

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

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

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

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

「很多者の箇条書き」と「边缘化したリスト構造」の无拘无束的な考え方と相まって、現在のドキュメントは很多者のみが適切に維持できるということです。ドキュメントに貢献する簡単な方法步骤は他にありません。問題は 2 つあります。まず、「各个者の箇条書き」の考え方に基づいて、制作者は経験の浅い人がドキュメントを台無しにすることを望んでおらず、メンテナーとの連携に多くの時間を費やさないと、ドキュメントのトーンを合わせるのが更加に困難です。

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

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

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

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

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

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

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

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

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

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

どのような状況においても实用なソリューションはすべて、現在私たちが手にしている情報の水灾に耐える用得着があります。彼らは、検索エンジン之内にアンカー ポイントがない状態で、この戦場に缴纳する用得着があります。素晴らしいリスト [^2] は良いアイデアです。優れたコンテンツを残す方法步骤を具备しますが、「排斥したリスト構造」と「很多者の箇条書き」の考え方に関して同じ問題があります。

このままの状態なら…

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

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

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

• ユーザーにドキュメントへの貢献を促し、ドキュメントの寻常的な目地を妨げないようにするにはどうすればよいですか?ドキュメンテーションのために、よりインタラクティブな体験をすることはできますか?ユーザーはページを離れずにドキュメントに真接貢献できますか?
• 静态の検索ソリューションに依存せず、半路ですべてのコンテキストの彼此之间接続性をもたらす、より良い検索エクスペリエンスのためにコンテキストを収集するにはどうすればよいでしょうか?
• ユーザーエクスペリエンスに益处をもたらす有机会性のある新しい構造を試して、時間をかけて繰り返したり、ユーザーが任意に選択できるようにする的方式は?

  
  

[^1]:[^2]: