@aigne/doc-smith 0.8.11-beta.6 → 0.8.11

package/docs/features-update-and-refine.md

@@ -2,11 +2,11 @@
 
 Keeping documentation synchronized with an evolving codebase is a methodical process. AIGNE DocSmith provides direct and flexible commands to keep your content current, either through automatic updates based on code changes or through precise, feedback-driven refinements.
 
-This guide covers the procedures to:
+This guide provides procedures for the following tasks:
 
-- Automatically update documents when source code is modified.
-- Regenerate specific documents using targeted feedback.
-- Adjust the overall documentation structure.
+*   Automatically updating documents when source code is modified.
+*   Regenerating specific documents using targeted feedback.
+*   Adjusting the overall documentation structure.
 
 ### Document Update Workflows
 
@@ -15,124 +15,76 @@ The following diagram illustrates the different workflows available for updating
 ```d2 Document Update Workflows
 direction: down
 
-developer: {
+Developer: {
   shape: c4-person
-  label: "Developer"
 }
 
-codebase: {
-  shape: cylinder
+Source-Code: {
   label: "Source Code"
 }
 
-updated-documentation: {
-  shape: cylinder
-  label: "Updated\nDocumentation"
+Documentation: {
+  label: "Documentation"
 }
 
-workflows: {
-  label: "Document Update Workflows"
+Action-Choice: {
+  label: "Choose Action"
+  shape: diamond
+}
+
+Generate-Sync: {
+  label: "aigne doc generate"
   shape: rectangle
 
-  automatic-updates: {
-    label: "Automatic Updates (Code-Driven)"
-    shape: rectangle
+  Change-Detection: {
+    label: "Detect Changes?"
+    shape: diamond
+  }
+  Regenerate-Affected: "Regenerate Affected"
+  Regenerate-All: "Regenerate All"
 
-    cmd-generate: {
-      label: "aigne doc generate"
-    }
+  Change-Detection -> Regenerate-Affected: "Yes (Default)"
+  Change-Detection -> Regenerate-All: "No\n(--forceRegenerate)"
+}
 
-    decision-force: {
-      label: "--forceRegenerate?"
-      shape: diamond
-    }
+Refine-Content: {
+  label: "aigne doc update"
+}
 
-    detect-changes: {
-      label: "Detect Changes"
-    }
+Refine-Structure: {
+  label: "aigne doc generate\n--feedback"
+}
 
-    regen-affected: {
-      label: "Regenerate\nAffected Docs"
-    }
+Developer -> Action-Choice
 
-    regen-all: {
-      label: "Regenerate\nAll Docs"
-    }
-  }
+Action-Choice -> Generate-Sync: "Sync with Code"
+Action-Choice -> Refine-Content: "Refine Doc Content"
+Action-Choice -> Refine-Structure: "Refine Doc Structure"
 
-  manual-refinements: {
-    label: "Manual Refinements (Feedback-Driven)"
-    shape: rectangle
-    grid-columns: 2
-    grid-gap: 100
-
-    refine-individual: {
-      label: "Refine Individual Docs"
-      shape: rectangle
-
-      cmd-update: {
-        label: "aigne doc update\n--feedback"
-      }
-
-      regen-specific: {
-        label: "Regenerate\nSpecific Doc"
-      }
-    }
-
-    optimize-structure: {
-      label: "Optimize Overall Structure"
-      shape: rectangle
-
-      cmd-generate-feedback: {
-        label: "aigne doc generate\n--feedback"
-      }
-
-      re-evaluate-plan: {
-        label: "Re-evaluate\nDocument Plan"
-      }
-    }
-  }
-}
+Source-Code -> Generate-Sync
 
-# --- Connections ---
-
-# Path 1: Automatic Updates
-developer -> codebase: "1. Makes changes"
-codebase -> workflows.automatic-updates.cmd-generate: "2. Runs command"
-workflows.automatic-updates.cmd-generate -> workflows.automatic-updates.decision-force
-workflows.automatic-updates.decision-force -> workflows.automatic-updates.detect-changes: "No"
-workflows.automatic-updates.detect-changes -> workflows.automatic-updates.regen-affected
-workflows.automatic-updates.decision-force -> workflows.automatic-updates.regen-all: "Yes"
-workflows.automatic-updates.regen-affected -> updated-documentation
-workflows.automatic-updates.regen-all -> updated-documentation
-
-# Path 2: Individual Refinement
-developer -> workflows.manual-refinements.refine-individual.cmd-update: "3. Provides\ncontent feedback"
-workflows.manual-refinements.refine-individual.cmd-update -> workflows.manual-refinements.refine-individual.regen-specific
-workflows.manual-refinements.refine-individual.regen-specific -> updated-documentation
-
-# Path 3: Structural Refinement
-developer -> workflows.manual-refinements.optimize-structure.cmd-generate-feedback: "4. Provides\nstructural feedback"
-workflows.manual-refinements.optimize-structure.cmd-generate-feedback -> workflows.manual-refinements.optimize-structure.re-evaluate-plan
-workflows.manual-refinements.optimize-structure.re-evaluate-plan -> updated-documentation: "Regenerate with\nNew Structure"
+Generate-Sync.Regenerate-Affected -> Documentation: "Update"
+Generate-Sync.Regenerate-All -> Documentation: "Update"
+Refine-Content -> Documentation: "Update"
+Refine-Structure -> Documentation: "Update"
 ```
 
 ---
 
 ## Automatic Updates with Change Detection
 
-When you execute the `aigne doc generate` command, DocSmith first analyzes your codebase to detect changes since the last generation. It then regenerates only the documents affected by these changes. This default behavior conserves time and reduces API usage.
+When you execute the `aigne doc generate` command, DocSmith first analyzes your codebase to detect changes since the last generation. It then regenerates only the documents affected by these changes. This default behavior conserves time and reduces API usage by avoiding redundant operations.
 
 ```shell icon=lucide:terminal
-# DocSmith will detect changes and update only what's necessary
+# DocSmith will detect changes and update only what is necessary
 aigne doc generate
 ```
 
-![DocSmith detects changes and regenerates only the required documents.](https://docsmith.aigne.io/image-bin/uploads/21a76b2f65d14d16a49c13d800f1e2c1.png)
+![DocSmith detects changes and regenerates only the required documents.](../assets/screenshots/doc-regenerate.png)
 
 ### Forcing a Full Regeneration
 
-To regenerate all documentation from scratch, bypassing the cache and change detection, use the `--forceRegenerate` flag. This is necessary when you have made significant configuration changes or require a complete rebuild to ensure consistency.
+To regenerate all documentation from scratch, bypassing the cache and change detection, use the `--forceRegenerate` flag. This is necessary when you have made significant configuration changes or require a complete rebuild to ensure consistency across all files.
 
 ```shell icon=lucide:terminal
 # Regenerate all documentation from the ground up
@@ -141,13 +93,15 @@ aigne doc generate --forceRegenerate
 
 ---
 
-## Refining Individual Documents
+## Refining Documents with Feedback
+
+You can refine documentation without corresponding code changes by providing direct feedback to the CLI commands. This is useful for improving clarity, adding examples, or adjusting the structure.
 
-To improve a specific document's content without corresponding code changes, use the `aigne doc update` command. This command allows you to provide targeted instructions for refinement.
+### Refining Individual Document Content
 
-This can be done interactively or non-interactively via command-line arguments.
+To improve a specific document's content, use the `aigne doc update` command. This command allows you to provide targeted instructions for refinement and can be run in two modes: interactive or non-interactive.
 
-### Interactive Mode
+#### Interactive Mode
 
 For a guided process, run the command without arguments. DocSmith will present a menu to select the document you wish to update. After selection, you will be prompted to enter your feedback.
 
@@ -156,9 +110,9 @@ For a guided process, run the command without arguments. DocSmith will present a
 aigne doc update
 ```
 
-![Interactively select the documents you wish to update.](https://docsmith.aigne.io/image-bin/uploads/75e9cf9823bb369c3d2b5a2e2da4ac06.png)
+![Interactively select the documents you wish to update.](../assets/screenshots/doc-update.png)
 
-### Direct Command-Line Updates
+#### Non-Interactive Mode
 
 For scripted or faster workflows, you can specify the document and feedback directly using flags. This enables precise, non-interactive updates.
 
@@ -167,26 +121,22 @@ For scripted or faster workflows, you can specify the document and feedback dire
 aigne doc update --docs overview.md --feedback "Add a more detailed FAQ section at the end."
 ```
 
-Key parameters for the `update` command are as follows:
+The primary parameters for the `update` command are as follows:
 
 | Parameter | Description |
-| --- | --- |
+| :--- | :--- |
 | `--docs` | The path to the document to be updated. This flag can be used multiple times for batch updates. |
-| `--feedback` | The specific instructions to be used when regenerating the content. |
-
----
-
-## Optimizing the Overall Structure
+| `--feedback` | A string containing the specific instructions to be used when regenerating the document's content. |
 
-In addition to refining individual document content, you can adjust the overall documentation structure. If the existing organization is suboptimal or a section is missing, you can provide feedback to the `generate` command.
+### Optimizing the Overall Structure
 
-This instructs DocSmith to re-evaluate the entire document plan based on your input.
+In addition to refining individual documents, you can adjust the overall documentation structure. If the existing organization is suboptimal or a section is missing, you can provide feedback to the `generate` command. This instructs DocSmith to re-evaluate the entire document plan based on your input.
 
 ```shell icon=lucide:terminal
 # Regenerate the documentation structure with specific feedback
 aigne doc generate --feedback "Remove the 'About' section and add a detailed 'API Reference'."
 ```
 
-This approach is intended for high-level changes to the document's table of contents, not for minor content edits.
+This approach is intended for high-level changes to the document's table of contents, not for minor content edits within a single file.
 
-Once your content is refined, the next step is to prepare it for a global audience. For instructions, see the [Translate Documentation](./features-translate-documentation.md) guide.
+Once your content is refined, the next step is to prepare it for a global audience. For instructions, see the [Translate Documentation](./features-translate-documentation.md) guide.

package/docs/features-update-and-refine.zh-TW.md

@@ -1,164 +1,119 @@
 # 更新與完善
 
-讓文件與不斷演進的程式碼庫保持同步是一個有條理的過程。AIGNE DocSmith 提供了直接而靈活的指令，可透過基於程式碼變更的自動更新，或透過精確、由回饋驅動的完善來讓您的內容保持最新。
+讓文件與不斷演進的程式碼庫保持同步是一項有條不紊的過程。AIGNE DocSmith 提供直接而靈活的指令，讓您能透過程式碼變更自動更新，或透過精確、由回饋驅動的完善方式，來保持內容的最新狀態。
 
-本指南涵蓋以下程序：
+本指南提供執行以下任務的程序：
 
-- 在原始碼被修改時自動更新文件。
-- 使用針對性的回饋重新生成特定文件。
-- 調整整體文件結構。
+*   在原始碼修改時自動更新文件。
+*   使用針對性的回饋重新產生特定文件。
+*   調整整體文件結構。
 
 ### 文件更新工作流程
 
-下圖說明了可用於更新文件的不同工作流程：
+下圖說明了更新文件可用的不同工作流程：
 
 ```d2 文件更新工作流程
 direction: down
 
-developer: {
+Developer: {
   shape: c4-person
-  label: "開發人員"
+  label: "開發者"
 }
 
-codebase: {
-  shape: cylinder
+Source-Code: {
   label: "原始碼"
 }
 
-updated-documentation: {
-  shape: cylinder
-  label: "已更新的\n文件"
+Documentation: {
+  label: "文件"
 }
 
-workflows: {
-  label: "文件更新工作流程"
+Action-Choice: {
+  label: "選擇操作"
+  shape: diamond
+}
+
+Generate-Sync: {
+  label: "aigne doc generate"
   shape: rectangle
 
-  automatic-updates: {
-    label: "自動更新（程式碼驅動）"
-    shape: rectangle
+  Change-Detection: {
+    label: "偵測變更？"
+    shape: diamond
+  }
+  Regenerate-Affected: "重新產生受影響部分"
+  Regenerate-All: "全部重新產生"
 
-    cmd-generate: {
-      label: "aigne doc generate"
-    }
+  Change-Detection -> Regenerate-Affected: "是 (預設)"
+  Change-Detection -> Regenerate-All: "否\n(--forceRegenerate)"
+}
 
-    decision-force: {
-      label: "--forceRegenerate？"
-      shape: diamond
-    }
+Refine-Content: {
+  label: "aigne doc update"
+}
 
-    detect-changes: {
-      label: "偵測變更"
-    }
+Refine-Structure: {
+  label: "aigne doc generate\n--feedback"
+}
 
-    regen-affected: {
-      label: "重新生成\n受影響文件"
-    }
+Developer -> Action-Choice
 
-    regen-all: {
-      label: "重新生成\n所有文件"
-    }
-  }
+Action-Choice -> Generate-Sync: "與程式碼同步"
+Action-Choice -> Refine-Content: "完善文件內容"
+Action-Choice -> Refine-Structure: "完善文件結構"
 
-  manual-refinements: {
-    label: "手動完善（回饋驅動）"
-    shape: rectangle
-    grid-columns: 2
-    grid-gap: 100
-
-    refine-individual: {
-      label: "完善個別文件"
-      shape: rectangle
-
-      cmd-update: {
-        label: "aigne doc update\n--feedback"
-      }
-
-      regen-specific: {
-        label: "重新生成\n特定文件"
-      }
-    }
-
-    optimize-structure: {
-      label: "優化整體結構"
-      shape: rectangle
-
-      cmd-generate-feedback: {
-        label: "aigne doc generate\n--feedback"
-      }
-
-      re-evaluate-plan: {
-        label: "重新評估\n文件計畫"
-      }
-    }
-  }
-}
+Source-Code -> Generate-Sync
 
-# --- Connections ---
-
-# Path 1: Automatic Updates
-developer -> codebase: "1. 進行變更"
-codebase -> workflows.automatic-updates.cmd-generate: "2. 執行指令"
-workflows.automatic-updates.cmd-generate -> workflows.automatic-updates.decision-force
-workflows.automatic-updates.decision-force -> workflows.automatic-updates.detect-changes: "否"
-workflows.automatic-updates.detect-changes -> workflows.automatic-updates.regen-affected
-workflows.automatic-updates.decision-force -> workflows.automatic-updates.regen-all: "是"
-workflows.automatic-updates.regen-affected -> updated-documentation
-workflows.automatic-updates.regen-all -> updated-documentation
-
-# Path 2: Individual Refinement
-developer -> workflows.manual-refinements.refine-individual.cmd-update: "3. 提供\n內容回饋"
-workflows.manual-refinements.refine-individual.cmd-update -> workflows.manual-refinements.refine-individual.regen-specific
-workflows.manual-refinements.refine-individual.regen-specific -> updated-documentation
-
-# Path 3: Structural Refinement
-developer -> workflows.manual-refinements.optimize-structure.cmd-generate-feedback: "4. 提供\n結構性回饋"
-workflows.manual-refinements.optimize-structure.cmd-generate-feedback -> workflows.manual-refinements.optimize-structure.re-evaluate-plan
-workflows.manual-refinements.optimize-structure.re-evaluate-plan -> updated-documentation: "以\n新結構重新生成"
+Generate-Sync.Regenerate-Affected -> Documentation: "更新"
+Generate-Sync.Regenerate-All -> Documentation: "更新"
+Refine-Content -> Documentation: "更新"
+Refine-Structure -> Documentation: "更新"
 ```
 
 ---
 
-## 具備變更偵測的自動更新
+## 透過變更偵測自動更新
 
-當您執行 `aigne doc generate` 指令時，DocSmith 會先分析您的程式碼庫以偵測自上次生成以來的變更。接著，它只會重新生成受這些變更影響的文件。這種預設行為可以節省時間並減少 API 的使用。
+當您執行 `aigne doc generate` 指令時，DocSmith 會先分析您的程式碼庫，以偵測自上次產生以來的變更。然後，它只會重新產生受這些變更影響的文件。這種預設行為可以節省時間並減少 API 使用量，避免了多餘的操作。
 
 ```shell icon=lucide:terminal
-# DocSmith 將偵測變更並僅更新必要部分
+# DocSmith 將偵測變更並僅更新必要的部分
 aigne doc generate
 ```
 
-![DocSmith 偵測變更並僅重新生成所需文件。](https://docsmith.aigne.io/image-bin/uploads/21a76b2f65d14d16a49c13d800f1e2c1.png)
+![DocSmith 偵測變更並僅重新產生所需的文件。](../assets/screenshots/doc-regenerate.png)
 
-### 強制完整重新生成
+### 強制完整重新產生
 
-若要從頭開始重新生成所有文件，繞過快取和變更偵測，請使用 `--forceRegenerate` 旗標。當您進行了重大的設定變更或需要完全重建以確保一致性時，這項操作是必要的。
+若要從頭開始重新產生所有文件，繞過快取和變更偵測，請使用 `--forceRegenerate` 旗標。當您進行了重大的設定變更或需要完全重建以確保所有檔案的一致性時，這項操作是必要的。
 
 ```shell icon=lucide:terminal
-# 從頭開始重新生成所有文件
+# 從頭開始重新產生所有文件
 aigne doc generate --forceRegenerate
 ```
 
 ---
 
-## 完善個別文件
+## 透過回饋完善文件
+
+您可以透過向 CLI 指令提供直接回饋，在沒有相應程式碼變更的情況下完善文件。這對於提高清晰度、新增範例或調整結構很有用。
 
-若要在沒有相應程式碼變更的情況下改善特定文件的內容，請使用 `aigne doc update` 指令。此指令允許您提供針對性的指示以進行完善。
+### 完善個別文件內容
 
-這可以透過互動模式或透過命令列參數以非互動方式完成。
+若要改善特定文件的內容，請使用 `aigne doc update` 指令。此指令允許您提供針對性的完善指示，並可以互動或非互動兩種模式執行。
 
-### 互動模式
+#### 互動模式
 
-若要進行引導式流程，請在不帶任何參數的情況下執行該指令。DocSmith 將會顯示一個選單，讓您選擇想要更新的文件。選擇後，系統將提示您輸入回饋。
+若要進行引導式流程，請在不帶任何參數的情況下執行該指令。DocSmith 將會顯示一個選單，讓您選擇要更新的文件。選擇後，系統會提示您輸入回饋。
 
 ```shell icon=lucide:terminal
-# 啟動互動式更新流程
+# 開始互動式更新流程
 aigne doc update
 ```
 
-![以互動方式選擇您希望更新的文件。](https://docsmith.aigne.io/image-bin/uploads/75e9cf9823bb369c3d2b5a2e2da4ac06.png)
+![以互動方式選擇您希望更新的文件。](../assets/screenshots/doc-update.png)
 
-### 直接透過命令列更新
+#### 非互動模式
 
 對於腳本化或更快速的工作流程，您可以使用旗標直接指定文件和回饋。這可以實現精確的非互動式更新。
 
@@ -167,26 +122,22 @@ aigne doc update
 aigne doc update --docs overview.md --feedback "Add a more detailed FAQ section at the end."
 ```
 
-以下是 `update` 指令的關鍵參數：
+`update` 指令的主要參數如下：
 
 | 參數 | 說明 |
-| --- | --- |
+| :--- | :--- |
 | `--docs` | 要更新的文件的路徑。此旗標可多次使用以進行批次更新。 |
-| `--feedback` | 重新生成內容時要使用的具體指示。 |
-
----
-
-## 優化整體結構
+| `--feedback` | 一個字串，包含重新產生文件內容時要使用的具體指示。 |
 
-除了完善個別文件內容外，您還可以調整整體的文件結構。如果現有組織不理想或缺少某個部分，您可以向 `generate` 指令提供回饋。
+### 最佳化整體結構
 
-這會指示 DocSmith 根據您的輸入重新評估整個文件計畫。
+除了完善個別文件外，您還可以調整整體文件結構。如果現有組織結構不佳或缺少某個部分，您可以向 `generate` 指令提供回饋。這會指示 DocSmith 根據您的輸入重新評估整個文件計畫。
 
 ```shell icon=lucide:terminal
-# 根據特定回饋重新生成文件結構
+# 透過特定回饋重新產生文件結構
 aigne doc generate --feedback "Remove the 'About' section and add a detailed 'API Reference'."
 ```
 
-此方法適用於對文件目錄進行高層次的變更，而非用於微小的內容編輯。
+此方法適用於對文件目錄進行高層次的變更，而非針對單一檔案內的微小內容編輯。
 
-一旦您的內容完善後，下一步就是為全球受眾準備。有關說明，請參閱 [翻譯文件](./features-translate-documentation.md) 指南。
+內容完善後，下一步是為全球受眾做準備。相關說明，請參閱 [翻譯文件](./features-translate-documentation.md) 指南。