ドキュメントの評価

ドキュメントが目標を達成しているか気になりますか？このガイドでは、ドキュメントの品質と完全性を体系的に評価し、改善を導くための明確で実行可能なレポートを提供する強力なツールであるevaluateコマンドを紹介します。評価の実行方法とその結果の解釈方法を学びます。

評価プロセス

evaluateコマンドは、ドキュメントの状態を完全に把握するために、包括的な2段階の分析を実行します。高レベルの構成と各ファイルの詳細の両方をチェックします。

構造評価
まず、ツールはドキュメント全体のアーキテクチャを検査します。トピックの階層が論理的であり、初期設定で定義した目標、対象読者、および深さを完全にカバーしていることを検証します。
コンテンツ評価
次に、個々のドキュメントを詳細に掘り下げます。この段階では、読みやすさ、一貫性、および明記された目的との整合性などの側面に基づいて、書かれたコンテンツの品質を評価します。また、コードスニペットの正確性も検証します。

両方の段階が完了すると、調査結果は詳細なHTMLレポートにまとめられ、スコア、特定された問題、および実行可能なフィードバックが提供されます。

評価の実行方法

評価プロセスを開始するには、プロジェクトのルートディレクトリから単一のコマンドを実行するだけです。

コマンドの実行

ターミナルを開き、evaluateコマンドを実行します。

aigne doc evaluate

aigne doc evaluate

デフォルトでは、コマンドは完了時に生成されたHTMLレポートをウェブブラウザで自動的に開きます。これを防ぐには、--open falseフラグを追加できます。

aigne doc evaluate --open false

aigne doc evaluate --open false

出力の確認

コマンドが実行されると、その進行状況が表示されます。完了すると、確認メッセージがターミナルに表示され、レポートファイルへのパスが提供されます。

✔ Generate evaluation report
Evaluation report generated successfully.
- JSON Report: .aigc/evaluate/20240520114500/integrity-report.json
- HTML Report: .aigc/evaluate/20240520114500/report.html

report.htmlファイルをブラウザで直接開いて、詳細な分析を表示できます。

評価レポートの理解

レポートは、評価結果を明確かつ整理された形で提供するように構成されており、注意が必要な領域を簡単に特定できます。

構造評価の詳細

このセクションは、ドキュメントの高レベルの構成に焦点を当てています。ドキュメント構造がプロジェクトの定義された目標とどの程度整合しているかを評価します。

側面	説明
目的の網羅性	ドキュメント構造が、「すぐに始める」や「特定のタスクを完了する」などの主要な目標を適切にサポートしているかを評価します。
対象読者の網羅性	構造が、「エンドユーザー（非技術者）」などの意図された対象読者にとって論理的に構成されているかを判断します。
深さの網羅性	構造によって示唆される詳細レベルが、「すべてのパラメータをカバーする」など、選択されたコンテンツの深さと一致しているかを確認します。

ドキュメントコンテンツ評価の詳細

このセクションでは、コンテンツの品質をファイルごとに分析します。各ドキュメントは、品質基準を満たしていることを確認するために、一連の標準化された基準に対してスコアリングされます。

側面	説明
読みやすさ	テキストがどれだけ読みやすく、理解しやすいかを測定します。
一貫性	ドキュメント内のトピックの論理的な流れと構成を評価します。
コンテンツ品質	提供される情報の正確性、関連性、および明確さを評価します。
整合性	すべてのドキュメントで用語、フォーマット、およびスタイルが一貫して使用されているかを確認します。
目的との整合性	コンテンツが指定されたドキュメントの目標をどの程度達成しているかを判断します。
対象読者との整合性	言語、トーン、および例が対象読者にとって適切であるかを評価します。
知識レベルとの整合性	コンテンツの複雑さが定義された読者の知識レベルと一致していることを検証します。

まとめ

evaluateコマンドを定期的に使用することは、高品質なドキュメントを維持するための重要な実践です。客観的な指標と具体的なフィードバックを提供し、コンテンツを体系的に改善することができます。レポートを確認した後、ターゲットを絞った改善を行い、ドキュメントができるだけ明確で効果的であることを確認できます。

レポートからのフィードバックを適用する方法の詳細については、ドキュメント更新ガイドを参照してください。