@aigne/doc-smith 0.8.12-beta.6 → 0.8.12-beta.8

package/docs/guides-evaluating-documents.md

@@ -1,66 +1,107 @@
 # Evaluating Documents
 
-The `evaluate` command provides a systematic process to assess the quality and alignment of your generated documentation. It analyzes both the overall structure and the content of individual documents against the goals you defined during the initial setup. This process results in a detailed report, helping you identify areas for improvement and ensure the documentation effectively serves its intended purpose and audience.
+The `evaluate` command provides a systematic method to assess the quality and completeness of your generated documentation. It analyzes both the overall document structure and the content of individual files against the criteria defined during project setup. The process concludes by generating a detailed report, which helps identify areas for improvement and ensures the documentation aligns with its intended purpose and audience.
 
-## How It Works
+## The Evaluation Process
 
-The evaluation process operates in two primary stages. First, it assesses the high-level document structure, and second, it analyzes the content of each individual document.
+The evaluation command executes a two-stage analysis to provide a comprehensive assessment of your documentation.
 
-1.  **Structure Evaluation**: The tool examines your documentation's overall organization (like a table of contents). It verifies whether the structure is logical and complete based on the documentation goals, target audience, and content depth you selected.
-2.  **Content Evaluation**: After analyzing the structure, the tool inspects each document's content. It scores the document against several quality dimensions, including readability, coherence, and accuracy. It also checks for the correct implementation of code examples.
+```d2
+direction: down
 
-Upon completion, the tool compiles the findings into a user-friendly HTML report, providing both high-level scores and detailed, actionable feedback.
+start: {
+  label: "Run Command\naignite evaluate"
+  shape: oval
+}
 
-## Running the Evaluation
+structure-eval: {
+  label: "Stage 1: Evaluate\nDocument Structure"
+  shape: rectangle
+}
 
-To initiate the evaluation process, execute the following command in your terminal:
+content-eval: {
+  label: "Stage 2: Evaluate\nDocument Content"
+  shape: rectangle
+}
+
+report-gen: {
+  label: "Generate Report"
+  shape: rectangle
+}
+
+output: {
+  label: "Output HTML &\nJSON Report Files"
+  shape: oval
+}
+
+start -> structure-eval: "Analyzes overall organization"
+structure-eval -> content-eval: "Analyzes each file individually"
+content-eval -> report-gen: "Aggregates all findings"
+report-gen -> output: "Saves report to disk"
+```
+
+1.  **Structure Evaluation**: The tool first examines the documentation's high-level organization, analogous to a table of contents. It verifies whether the structure is logical and complete based on the specified documentation goals, target audience, and content depth.
+2.  **Content Evaluation**: Following the structural analysis, the tool inspects the content of each document. It scores each file against several quality dimensions, including readability, coherence, and factual accuracy. It also validates the correctness and formatting of included code snippets.
+
+The findings from both stages are compiled into an HTML report that presents high-level scores and specific, actionable feedback.
+
+## How to Run an Evaluation
+
+To initiate the evaluation process, execute the `evaluate` command from your project's root directory.
+
+### Execute the Command
+
+Open your terminal and run the following command:
 
 ```bash
 aignite evaluate
 ```
 
-The command will display progress as it analyzes your documentation. Once finished, it will provide a message indicating the location of the generated report files.
+The tool will display its progress as it analyzes the documentation.
+
+### Review the Output
+
+Upon completion, a confirmation message will appear in the terminal, specifying the location of the generated report files.
 
 ```text
 ✔ Generate evaluation report
 Evaluation report generated successfully.
-- JSON Report: .aigc/evaluate/20231027103000/integrity-report.json
-- HTML Report: .aigc/evaluate/20231027103000/report.html
+- JSON Report: .aigc/evaluate/20240520114500/integrity-report.json
+- HTML Report: .aigc/evaluate/20240520114500/report.html
 ```
 
-You can open the `report.html` file in your web browser to view the detailed analysis.
+Open the `report.html` file in a web browser to view the detailed analysis.
 
-## Understanding the Report
+## Understanding the Evaluation Report
 
-The evaluation report is organized into two main sections, reflecting the two stages of the analysis process.
+The report is organized into sections that correspond to the stages of the evaluation process, providing a clear breakdown of the analysis.
 
-### Structure Evaluation
+### Structure Evaluation Details
 
-This section provides feedback on the overall architecture of your documentation. It measures how well the generated document hierarchy aligns with your specified configuration.
+This section presents feedback on the overall architecture of your documentation. It measures how effectively the document hierarchy aligns with the project's configuration.
 
 | Dimension | Description |
 | :--- | :--- |
-| **Purpose Coverage** | Assesses if the document structure effectively supports the primary goals you selected (e.g., "Get started quickly"). |
-| **Audience Coverage** | Determines if the structure is appropriate for your defined target audience (e.g., "non-technical users"). |
-| **Depth Coverage** | Checks if the level of detail in the structure matches your selected content depth (e.g., "covers all parameters"). |
+| **Purpose Coverage** | Assesses if the document structure adequately supports the primary goals selected (e.g., "Get started quickly"). |
+| **Audience Coverage** | Determines if the structure is organized in a way that is suitable for the defined target audience (e.g., "non-technical users"). |
+| **Depth Coverage** | Checks if the level of detail implied by the structure matches the selected content depth (e.g., "covers all parameters"). |
 
-### Document Content Evaluation
+### Document Content Evaluation Details
 
-This section provides a document-by-document breakdown of content quality. Each document is scored based on a set of standardized criteria.
+This section provides a file-by-file breakdown of content quality. Each document is scored based on a set of standardized criteria.
 
 | Dimension | Description |
 | :--- | :--- |
-| **Readability** | Measures how easy the text is to read and comprehend. |
+| **Readability** | Measures the ease with which the text can be read and understood. |
 | **Coherence** | Evaluates the logical flow and organization of information within the document. |
 | **Content Quality** | Assesses the accuracy, relevance, and clarity of the information presented. |
-| **Consistency** | Checks for uniform terminology, formatting, and style across the document. |
-| **Purpose Alignment** | Determines how well the content meets the specified documentation goals. |
-| **Audience Alignment** | Assesses if the language and examples are suitable for the target audience. |
-| **Knowledge Level Alignment** | Checks if the content complexity matches the defined reader knowledge level. |
-| **Navigability** | Evaluates the effectiveness of internal links and structural elements that help users find information. |
+| **Consistency** | Checks for uniform terminology, formatting, and style throughout the document. |
+| **Purpose Alignment** | Determines how well the content fulfills the specified documentation goals. |
+| **Audience Alignment** | Assesses if the language, tone, and examples are appropriate for the target audience. |
+| **Knowledge Level Alignment** | Checks if the content's complexity matches the defined reader knowledge level. |
 
 ## Summary
 
-Using the `evaluate` command is a crucial step in maintaining accurate and effective documentation. It provides concrete metrics and specific feedback, allowing you to refine your content methodically. After reviewing the evaluation report, you can proceed to make targeted improvements.
+Using the `evaluate` command is an essential step for maintaining accurate and effective documentation. It provides objective metrics and specific feedback, enabling a methodical approach to refining your content. After reviewing the evaluation report, you can make targeted improvements to enhance documentation quality.
 
-For the next steps on modifying your documents based on this feedback, please see the guide on [Updating Documentation](./guides-updating-documentation.md).
+For guidance on modifying your documents based on this feedback, refer to the [Updating Documentation](./guides-updating-documentation.md) guide.

package/docs/guides-generating-documentation.ja.md

@@ -1,12 +1,12 @@
 # ドキュメントの生成
 
-このガイドでは、プロジェクトのソースファイルからドキュメント一式を作成するための体系的な手順を説明します。このプロセスは `aigne doc generate` コマンドを使用して開始されます。このコマンドはコードベースを分析し、論理的な構造を提案し、各ドキュメントのコンテンツを作成します。
+このガイドでは、プロジェクトのソースファイルから完全なドキュメント一式を作成するための体系的な手順を説明します。このプロセスは `aigne doc generate` コマンドを使用して開始します。このコマンドはコードベースを分析し、論理的な構造を提案し、各ドキュメントのコンテンツを書き込みます。
 
-このコマンドは、ドキュメントを最初に作成するための主要なツールです。作成後のドキュメントの修正については、[ドキュメントの更新](./guides-updating-documentation.md)ガイドを参照してください。
+このコマンドは、ドキュメントを最初に作成するための主要なツールです。作成済みのドキュメントを修正する場合は、[ドキュメントの更新](./guides-updating-documentation.md)ガイドを参照してください。
 
-### 生成のワークフロー
+### 生成ワークフロー
 
-`generate` コマンドは、ドキュメントを構築するための一連の自動化されたステップを実行します。このプロセスは対話形式で設計されており、コンテンツが書き込まれる前に提案された構造を確認し、承認することができます。
+`generate` コマンドは、ドキュメントを構築するための一連の自動化されたステップを実行します。このプロセスは対話形式で設計されており、コンテンツが書き込まれる前に、提案された構造を確認・承認できます。
 
 ```d2
 direction: down
@@ -22,12 +22,12 @@ run_command: {
 }
 
 check_config: {
-  label: "設定ファイルが存在するか？"
+  label: "設定ファイルは存在するか？"
   shape: diamond
 }
 
 interactive_setup: {
-  label: "対話型セットアップのガイド"
+  label: "対話型セットアップをガイド"
   shape: rectangle
   tooltip: ".aigne/doc-smith/config.yaml が見つからない場合、対話型セットアップがトリガーされます。"
 }
@@ -43,14 +43,14 @@ review_structure: {
 }
 
 user_approve: {
-  label: "構造を承認しますか？"
+  label: "構造を承認するか？"
   shape: diamond
 }
 
 provide_feedback: {
-  label: "構造を改善するためのフィードバックを提供"
+  label: "構造を洗練させるためのフィードバックを提供"
   shape: rectangle
-  tooltip: "ユーザーは、セクションの名前の変更、追加、削除などの変更を要求できます。"
+  tooltip: "ユーザーはセクションの名前変更、追加、削除などの変更を要求できます。"
 }
 
 generate_content: {
@@ -88,61 +88,63 @@ generate_content -> end
 
 ドキュメントを生成するには、ターミナルでプロジェクトのルートディレクトリに移動し、以下の手順に従ってください。
 
-### 1. Generate コマンドの実行
+### 1. 生成コマンドの実行
 
-`generate` コマンドを実行してプロセスを開始します。ツールはプロジェクトのファイルと構造の分析から開始します。
+`generate` コマンドを実行してプロセスを開始します。ツールはプロジェクトのファイルと構造の分析から始めます。
 
 ```bash 基本的な生成コマンド
 aigne doc generate
 ```
 
-簡潔にするために、エイリアス `gen` または `g` を使用することもできます。
+簡潔にするために、エイリアスの `gen` や `g` を使用することもできます。
 
 ### 2. ドキュメント構造の確認
 
-分析が完了すると、ツールは提案されたドキュメント構造を提示します。この構造は、作成されるドキュメントの階層的な計画です。
-
-この計画を確認するよう求められます。
+分析が完了すると、ツールは提案されたドキュメント構造を表示し、確認を求めます。
 
 ```
-ドキュメントの構造を最適化しますか？
-タイトルを編集したり、セクションを再編成したりできます。
-❯ 問題ありません - 現在の構造で続行します
-  はい、構造を最適化します
+ドキュメント構造を最適化しますか？
+❯ いいえ、問題ありません
+  はい、構造を最適化します（例：「はじめに」を「クイックスタート」に名称変更、「APIリファレンス」を「設定」の前に移動するなど）
 ```
 
--   **問題ありません - 現在の構造で続行します**: このオプションを選択すると、提案された構造を承認し、直接コンテンツ生成に進みます。
--   **はい、構造を最適化します**: このオプションは、計画を修正したい場合に選択します。プレーンテキストで、「'API' を 'API リファレンス' に変更」や「'デプロイ' のための新しいセクションを追加」などのフィードバックを提供できます。AI はあなたのフィードバックに基づいて構造を修正し、再度確認することができます。このサイクルは、構造があなたの要件を満たすまで繰り返すことができます。
+-   **いいえ、問題ありません**: このオプションを選択すると、提案された構造を承認し、直接コンテンツ生成に進みます。
+-   **はい、構造を最適化します**: このオプションを選択すると、プランを修正できます。ツールは対話ループでフィードバックを求めます。次のようなプレーンテキストで指示を与えることができます。
+    -   `「トラブルシューティング」という新しいドキュメントを追加`
+    -   `「レガシー機能」ドキュメントを削除`
+    -   `「インストール」を構造の最上部に移動`
+
+    フィードバックのたびに、AIが構造を修正し、再度確認できます。フィードバックを入力せずにEnterキーを押すと、ループを終了して最終的な構造を承認します。
 
 ### 3. コンテンツの生成
 
-ドキュメント構造が承認されると、DocSmith は計画内の各ドキュメントの詳細なコンテンツの生成を開始します。このプロセスは自動的に実行され、その所要時間はプロジェクトの規模と複雑さによって異なります。
+ドキュメント構造が承認されると、DocSmithはプラン内の各ドキュメントの詳細なコンテンツの生成を開始します。このプロセスは自動的に実行され、所要時間はプロジェクトの規模と複雑さによって異なります。
 
 完了すると、生成されたファイルは設定で指定された出力ディレクトリ（例：`./docs`）に保存されます。
 
-## コマンドのパラメータ
+## コマンドパラメータ
 
 `generate` コマンドは、その動作を制御するためのいくつかのオプションパラメータを受け入れます。
 
-| パラメータ          | 説明                                                                                                                                     | 例                                                                                  |
-| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
-| `--forceRegenerate` | 既存の構造やコンテンツをすべて無視して、すべてのドキュメントをゼロから再構築します。これは、白紙の状態からやり直す場合に便利です。             | `aigne doc generate --forceRegenerate`                                              |
-| `--feedback`        | 構造生成フェーズで AI をガイドするための初期指示を提供します。                                                                             | `aigne doc generate --feedback "API の例を増やし、トラブルシューティングのセクションを追加してください"` |
-| `--glossary`        | ドキュメント全体で一貫した用語の使用を保証するために、用語集ファイル（`.md`）を指定します。                                                  | `aigne doc generate --glossary @/path/to/glossary.md`                             |
+| パラメータ | 説明 | 例 |
+|---|---|---|
+| `--forceRegenerate` | 既存の構造やコンテンツをすべて無視して、すべてのドキュメントを最初から再構築します。完全にリセットしたい場合に便利です。 | `aigne doc generate --forceRegenerate` |
+| `--feedback` | 対話型の確認が始まる前に、構造生成フェーズでAIをガイドするための初期のテキストベースの指示を提供します。 | `aigne doc generate --feedback "Add more API examples"` |
+| `--glossary` | 用語集ファイル（例：`glossary.md`）を指定して、ドキュメント全体で一貫した用語の使用を保証します。 | `aigne doc generate --glossary @/path/to/glossary.md` |
 
-### 例：完全な再構築を強制する
+### 例：完全な再構築の強制
 
 以前に生成されたすべてのドキュメントを破棄し、コードの現在の状態に基づいて新しいセットを作成したい場合は、`--forceRegenerate` フラグを使用します。
 
-```bash 再生成の強制
+```bash 再構築の強制
 aigne doc generate --forceRegenerate
 ```
 
 ## まとめ
 
-`generate` コマンドは、初期プロジェクトドキュメントを作成するプロセス全体を統括します。自動化されたコード分析と対話的なレビュープロセスを組み合わせることで、構造化された関連性の高いドキュメント一式を生成します。
+`generate` コマンドは、初期プロジェクトドキュメントを作成するプロセス全体を統括します。自動化されたコード分析と対話型の確認プロセスを組み合わせることで、構造化された関連性の高いドキュメント一式を生成します。
 
-ドキュメントが生成された後、次のことを行うことができます。
+ドキュメントが生成されたら、次のような操作ができます。
 
 -   [ドキュメントの更新](./guides-updating-documentation.md): 特定のドキュメントに変更を加える。
 -   [ドキュメントの翻訳](./guides-translating-documentation.md): コンテンツを他の言語に翻訳する。

package/docs/guides-generating-documentation.md

@@ -1,149 +1,89 @@
 # Generating Documentation
 
-This guide provides a systematic procedure for creating a complete set of documentation from your project's source files. The process is initiated using the `aigne doc generate` command, which analyzes your codebase, proposes a logical structure, and then writes the content for each document.
-
-This command is the primary tool for the initial creation of your documentation. For modifying documents after they have been created, refer to the [Updating Documentation](./guides-updating-documentation.md) guide.
-
-### The Generation Workflow
-
-The `generate` command executes a sequence of automated steps to build your documentation. The process is designed to be interactive, allowing you to review and approve the proposed structure before content is written.
-
-```d2
-direction: down
-
-start: {
-  label: "Start"
-  shape: oval
-}
-
-run_command: {
-  label: "Run 'aigne doc generate'"
-  shape: rectangle
-}
-
-check_config: {
-  label: "Configuration file exists?"
-  shape: diamond
-}
-
-interactive_setup: {
-  label: "Guide through interactive setup"
-  shape: rectangle
-  tooltip: "If .aigne/doc-smith/config.yaml is not found, an interactive setup is triggered."
-}
-
-propose_structure: {
-  label: "Analyze project and propose document structure"
-  shape: rectangle
-}
-
-review_structure: {
-  label: "User reviews the proposed structure"
-  shape: rectangle
-}
-
-user_approve: {
-  label: "Approve structure?"
-  shape: diamond
-}
-
-provide_feedback: {
-  label: "Provide feedback to refine structure"
-  shape: rectangle
-  tooltip: "User can request changes like renaming, adding, or removing sections."
-}
-
-generate_content: {
-  label: "Generate content for all documents"
-  shape: rectangle
-}
-
-end: {
-  label: "End"
-  shape: oval
-}
-
-start -> run_command
-run_command -> check_config
-check_config -> interactive_setup: {
-  label: "No"
-}
-interactive_setup -> propose_structure
-check_config -> propose_structure: {
-  label: "Yes"
-}
-propose_structure -> review_structure
-review_structure -> user_approve
-user_approve -> provide_feedback: {
-  label: "No"
-}
-provide_feedback -> review_structure
-user_approve -> generate_content: {
-  label: "Yes"
-}
-generate_content -> end
-```
+This guide provides a step-by-step process for creating a new set of documentation for your project using the `generate` command. This is the primary command used to transform your source files into a structured set of documents from start to finish.
+
+The generation process is designed to be systematic and interactive, ensuring the final output meets your project's specific needs.
 
-## Step-by-Step Process
+## The Generation Process
 
-To generate your documentation, navigate to the root directory of your project in your terminal and follow these steps.
+When you run `aigne doc generate`, the tool follows a methodical process to create your documentation. Here is a breakdown of each step.
 
-### 1. Run the Generate Command
+### Step 1: Initiate Generation
 
-Execute the `generate` command to begin the process. The tool will start by analyzing your project's files and structure.
+To begin, navigate to your project's root directory in your terminal and execute the core command.
 
-```bash Basic Generation Command
+```bash title="Terminal" icon=lucide:terminal
 aigne doc generate
 ```
 
-You can also use the aliases `gen` or `g` for brevity.
+This single command initiates the entire documentation creation workflow. If it's your first time running the command, you will be guided through an interactive setup process.
 
-### 2. Review the Documentation Structure
+![Generate Documentation Dialog](https://docsmith.aigne.io/image-bin/uploads/d409b85c2c7760778c18251e06d997d9.png)
 
-After the analysis is complete, the tool will present a proposed documentation structure. This structure is a hierarchical plan of the documents that will be created.
+### Step 2: Code Analysis and Structure Planning
 
-You will be prompted to review this plan:
+First, DocSmith analyzes your source code to understand its structure, components, and relationships. Based on this analysis, it proposes an initial documentation structure. This plan organizes topics into a logical hierarchy, which may include sections like "Getting Started," "Guides," and "API Reference," tailored to your project's content.
 
-```
-Would you like to optimize the documentation structure?
-You can edit titles, reorganize sections.
-❯ Looks good - proceed with current structure
-  Yes, optimize the structure
-```
+### Step 3: Interactive Structure Review
+
+After the initial structure is planned, you will be prompted to review it in the terminal. This is a critical step that allows you to refine the organization of your documents before the content is written.
+
+You can either approve the structure as is or provide feedback in plain language to make changes.
+
+![Reviewing the Documentation Structure](https://docsmith.aigne.io/image-bin/uploads/c530510525d8041c304d9c0258169904.png)
+
+Examples of feedback you can provide:
+
+*   Rename a section (e.g., change "Getting Started" to "Quick Start").
+*   Add a new document for "Troubleshooting."
+*   Remove a document that is not needed.
+*   Reorder sections to place "API Reference" before "Configuration."
 
--   **Looks good - proceed with current structure**: Select this option to approve the proposed structure and proceed directly to content generation.
--   **Yes, optimize the structure**: Select this option if you wish to modify the plan. You will be able to provide feedback in plain text, such as "Rename 'API' to 'API Reference'" or "Add a new section for 'Deployment'." The AI will revise the structure based on your feedback, and you can review it again. This cycle can be repeated until the structure meets your requirements.
+The tool will apply your feedback and present the updated structure for another review. You can repeat this process until the structure aligns perfectly with your requirements.
 
-### 3. Content Generation
+### Step 4: Content Creation
 
-Once the documentation structure is approved, DocSmith will begin generating the detailed content for each document in the plan. This process runs automatically, and its duration depends on the size and complexity of your project.
+Once you approve the final structure, DocSmith proceeds to generate the detailed content for each document. It reads the relevant source files and writes clear explanations, code examples, and descriptions for every planned section. This process is executed for all documents in the approved plan.
 
-Upon completion, the generated files will be saved to the output directory specified in your configuration (e.g., `./docs`).
+### Step 5: Completion
 
-## Command Parameters
+When the process is complete, you will see a confirmation message indicating that the documentation has been generated successfully. The output files will be located in the directory specified in your configuration (the default is `./docs`).
 
-The `generate` command accepts several optional parameters to control its behavior.
+![Documentation Generated Successfully](https://docsmith.aigne.io/image-bin/uploads/19c72054cd662d51259e8f668571891e.png)
 
-| Parameter           | Description                                                                                                                              | Example                                                                     |
-| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
-| `--forceRegenerate` | Rebuilds all documentation from scratch, ignoring any existing structure or content. This is useful for starting over with a clean slate. | `aigne doc generate --forceRegenerate`                                        |
-| `--feedback`        | Provides initial instructions to guide the AI during the structure generation phase.                                                     | `aigne doc generate --feedback "Add more API examples and a troubleshooting section"` |
-| `--glossary`        | Specifies a glossary file (`.md`) to ensure consistent use of terminology throughout the documentation.                                   | `aigne doc generate --glossary @/path/to/glossary.md`                       |
+## Command Options
 
-### Example: Forcing a Complete Rebuild
+You can modify the behavior of the `generate` command by using optional flags. These flags provide more control over the generation process.
 
-If you want to discard all previously generated documents and create a new set based on the current state of your code, use the `--forceRegenerate` flag.
+| Option                | Description                                                                                                                                                               |
+| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `--forceRegenerate`   | Re-creates all documentation from scratch, ignoring any existing files. This is useful if you have made significant changes to your source code or want a completely fresh build. |
+| `--glossary <path>`   | Specifies a glossary file (e.g., `--glossary @glossary.md`). This ensures that technical terms are defined and used consistently across all generated documents.               |
 
-```bash Forcing Regeneration
+### Example Usage
+
+Here are a few examples demonstrating how to use the command with its options.
+
+**Standard Generation**
+This is the most common use case for creating your initial set of documents.
+```bash title="Terminal" icon=lucide:terminal
+aigne doc generate
+```
+
+**Forced Regeneration**
+Use this command when you need to discard all existing documents and rebuild them entirely.
+```bash title="Terminal" icon=lucide:terminal
 aigne doc generate --forceRegenerate
 ```
 
-## Summary
+**Using a Glossary**
+To ensure consistent terminology, provide a path to your glossary file.
+```bash title="Terminal" icon=lucide:terminal
+aigne doc generate --glossary @./glossary.md
+```
 
-The `generate` command orchestrates the entire process of creating your initial project documentation. It combines automated code analysis with an interactive review process to produce a structured and relevant set of documents.
+## Summary
 
-After your documents are generated, you may want to:
+You have now learned the complete process for generating documentation from your project's source files. This workflow involves initiating the command, interactively reviewing the proposed structure, and allowing the tool to write the content.
 
--   [Update Documentation](./guides-updating-documentation.md): Make changes to specific documents.
--   [Translate Documentation](./guides-translating-documentation.md): Translate your content into other languages.
--   [Publishing Your Docs](./guides-publishing-your-docs.md): Make your documentation available online.
+After generating your documents, your next steps might be to [update specific documents](./guides-updating-documentation.md) with new information or [publish your documentation](./guides-publishing-your-docs.md) to make it accessible to your audience.

package/docs/guides-generating-documentation.zh-TW.md

@@ -1,12 +1,12 @@
 # 產生文件
 
-本指南提供了一套系統化程序，說明如何從專案的原始檔案建立完整文件。此流程使用 `aigne doc generate` 命令啟動，該命令會分析您的程式碼庫、提出邏輯結構，然後為每份文件撰寫內容。
+本指南提供了一套系統化程序，可從您的專案原始檔案建立一套完整的文件。此程序透過 `aigne doc generate` 指令啟動，該指令會分析您的程式碼庫、提出邏輯結構，然後為每份文件撰寫內容。
 
-此命令是初次建立您文件的主要工具。若要在文件建立後進行修改，請參閱 [更新文件](./guides-updating-documentation.md) 指南。
+此指令是初次建立文件的主要工具。若要在文件建立後進行修改，請參閱 [更新文件](./guides-updating-documentation.md) 指南。
 
 ### 產生工作流程
 
-`generate` 命令會執行一系列自動化步驟來建立您的文件。此過程設計為互動式，讓您能在內容寫入前，審查並核准建議的結構。
+`generate` 指令會執行一系列自動化步驟來建置您的文件。此程序設計為互動式，讓您能在內容撰寫前審閱並批准建議的結構。
 
 ```d2
 direction: down
@@ -38,12 +38,12 @@ propose_structure: {
 }
 
 review_structure: {
-  label: "使用者審查建議的結構"
+  label: "使用者審閱建議的結構"
   shape: rectangle
 }
 
 user_approve: {
-  label: "核准結構？"
+  label: "批准結構？"
   shape: diamond
 }
 
@@ -54,7 +54,7 @@ provide_feedback: {
 }
 
 generate_content: {
-  label: "為所有文件產生內容"
+  label: "為所有文件生成內容"
   shape: rectangle
 }
 
@@ -86,53 +86,55 @@ generate_content -> end
 
 ## 逐步流程
 
-若要產生您的文件，請在您的終端機中導覽至專案的根目錄，並遵循以下步驟。
+若要產生您的文件，請在終端機中導覽至您專案的根目錄，並依照下列步驟操作。
 
-### 1. 執行 Generate 命令
+### 1. 執行 Generate 指令
 
-執行 `generate` 命令以開始此流程。該工具將首先分析您專案的檔案和結構。
+執行 `generate` 指令以開始此程序。工具將首先分析您專案的檔案與結構。
 
-```bash 基本產生命令
+```bash 基本產生指令
 aigne doc generate
 ```
 
-您也可以使用別名 `gen` 或 `g` 以求簡潔。
+為求簡潔，您也可以使用別名 `gen` 或 `g`。
 
-### 2. 審查文件結構
+### 2. 審閱文件結構
 
-分析完成後，該工具將呈現一個建議的文件結構。此結構是將要建立的各份文件的一個階層式規劃。
-
-系統會提示您審查此計畫：
+分析完成後，工具將顯示建議的文件結構，並提示您進行審閱：
 
 ```
-您想最佳化文件結構嗎？
-您可以編輯標題、重組章節。
-❯ 看起來不錯 - 繼續使用目前結構
-  是，最佳化結構
+Would you like to optimize the documentation structure?
+❯ No, looks good
+  Yes, optimize the structure (e.g. rename 'Getting Started' to 'Quick Start', move 'API Reference' before 'Configuration')
 ```
 
--   **看起來不錯 - 繼續使用目前結構**：選擇此選項以核准建議的結構，並直接進入內容產生階段。
--   **是，最佳化結構**：如果您希望修改計畫，請選擇此選項。您將能夠以純文字形式提供回饋，例如「將『API』重新命名為『API 參考』」或「新增一個『部署』的章節」。AI 將根據您的回饋修訂結構，您可以再次審查。此循環可以重複進行，直到結構符合您的要求。
+-   **不，看起來不錯**：選擇此選項可批准建議的結構，並直接進入內容產生階段。
+-   **是的，最佳化結構**：選擇此選項可修改計畫。工具接著會以互動式循環徵詢您的回饋。您可以用純文字提供指令，例如：
+    -   `新增一份名為「疑難排解」的文件`
+    -   `移除「舊版功能」文件`
+    -   `將「安裝」移至結構頂部`
+
+    在每次回饋後，AI 將會修訂結構，您可以再次審閱。若要結束循環並批准最終結構，直接按下 Enter 鍵，不輸入任何回饋即可。
 
 ### 3. 內容產生
 
-文件結構一經核准，DocSmith 將開始為計畫中的每份文件產生詳細內容。此過程會自動執行，其持續時間取決於您專案的規模與複雜度。
+文件結構一經批准，DocSmith 將開始為計畫中的每份文件產生詳細內容。此過程會自動執行，其持續時間取決於您專案的規模與複雜度。
 
 完成後，產生的檔案將儲存至您設定中指定的輸出目錄（例如 `./docs`）。
 
-## 命令參數
+## 指令參數
 
-`generate` 命令接受數個可選參數來控制其行為。
+`generate` 指令接受數個選用參數以控制其行為。
 
 | 參數 | 說明 | 範例 |
-| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
-| `--forceRegenerate` | 從頭開始重建所有文件，忽略任何現有的結構或內容。這在您想從頭開始時很有用。 | `aigne doc generate --forceRegenerate` |
-| `--feedback` | 提供初始指令，以在結構產生階段指導 AI。 | `aigne doc generate --feedback "新增更多 API 範例和疑難排解章節"` |
-| `--glossary` | 指定一個詞彙表檔案（`.md`），以確保在整個文件中術語使用的一致性。 | `aigne doc generate --glossary @/path/to/glossary.md` |
+|---|---|---|
+| `--forceRegenerate` | 從頭開始重建所有文件，忽略任何現有的結構或內容。當您想要完全重置時，此選項非常有用。 | `aigne doc generate --forceRegenerate` |
+| `--feedback` | 在互動式審閱開始前，提供初始的文字指令，以在結構產生階段指導 AI。 | `aigne doc generate --feedback "新增更多 API 範例"` |
+| `--glossary` | 指定一個詞彙表檔案（例如 glossary.md），以確保在整個文件中術語使用的一致性。 | `aigne doc generate --glossary @/path/to/glossary.md` |
 
-### 範例：強制完全重建
+### 範例：強制完整重建
 
-如果您想捨棄所有先前產生的文件，並根據您程式碼的目前狀態建立一套新的文件，請使用 `--forceRegenerate` 旗標。
+如果您想捨棄所有先前產生的文件，並根據您程式碼的當前狀態建立一套新的文件，請使用 `--forceRegenerate` 旗標。
 
 ```bash 強制重新產生
 aigne doc generate --forceRegenerate
@@ -140,10 +142,10 @@ aigne doc generate --forceRegenerate
 
 ## 總結
 
-`generate` 命令統籌了建立您初始專案文件的整個流程。它結合了自動化程式碼分析與互動式審查流程，以產出一套結構化且相關的文件。
+`generate` 指令統籌了建立您初始專案文件的整個過程。它結合了自動化程式碼分析與互動式審閱流程，以產出一套結構化且相關的文件。
 
 文件產生後，您可能會想：
 
 -   [更新文件](./guides-updating-documentation.md)：對特定文件進行變更。
 -   [翻譯文件](./guides-translating-documentation.md)：將您的內容翻譯成其他語言。
--   [發佈您的文件](./guides-publishing-your-docs.md)：將您的文件發佈到網路上。
+-   [發布您的文件](./guides-publishing-your-docs.md)：將您的文件發布上線。