write-docs

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Write Documentation

编写文档

Write accurate, user-focused documentation with real examples by executing operations through the user.

通过让用户执行操作，使用真实示例编写准确、以用户为中心的文档。

Principles

原则

Execute-then-document: Never write examples without real output
Chunk-by-chunk: Write one section at a time, get confirmation before proceeding
User-focused: Write for users, not developers
Validate prerequisites: Run setup steps from existing docs to verify they work
Claude runs infrastructure, user runs MCP: Claude executes all bash/infrastructure commands. Only ask user for MCP client interactions (the actual user-facing examples).
Fix docs when broken: If existing docs don't work during setup, STOP and discuss updating those docs before proceeding.

先执行再记录：绝不要在没有真实输出的情况下编写示例
分块编写：一次编写一个章节，获得确认后再继续
以用户为中心：为用户而非开发者编写内容
验证前置条件：运行现有文档中的设置步骤，验证其有效性
Claude 负责基础设施操作，用户负责 MCP 操作：Claude 执行所有 bash/基础设施命令。仅请求用户进行 MCP 客户端交互（即实际面向用户的示例）。
文档出错时及时修复：如果设置过程中现有文档无法正常工作，请暂停并讨论更新文档，之后再继续。

Workflow

工作流程

Step 1: Identify the Documentation Target

步骤1：确定文档目标

Ask the user what documentation to write. Options:

New feature guide (e.g., "knowledge base guide")
Update existing guide
API reference
Setup/configuration guide

询问用户要编写的文档类型，可选类型：

新功能指南（例如：“知识库指南”）
更新现有指南
API 参考文档
安装/配置指南

Step 2: Fresh Environment Setup

步骤2：搭建全新环境

ALWAYS start with a clean test cluster to ensure reproducible documentation.

Follow the actual docs (
docs/setup/mcp-setup.md
) - this validates they work.

Claude executes all infrastructure steps directly using Bash tool:

Tear down existing test cluster if present

bash

kind delete cluster --name dot-test 2>/dev/null || true
rm -f ./kubeconfig.yaml

Create fresh Kind cluster with local kubeconfig

bash

kind create cluster --name dot-test --kubeconfig ./kubeconfig.yaml
export KUBECONFIG=./kubeconfig.yaml

Install prerequisites (ingress controller)

bash

kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/deploy/static/provider/kind/deploy.yaml
# Wait for ingress to be ready
kubectl wait --namespace ingress-nginx --for=condition=ready pod --selector=app.kubernetes.io/component=controller --timeout=300s

Follow docs/setup/mcp-setup.md (skip controller if not needed for the feature)
- Step 1: Set environment variables (use existing API keys from env)
- Step 2: Install controller via Helm (skip if feature doesn't need it)
- Step 3: Install MCP server via Helm
- Step 4: Tell user to configure MCP client
- Step 5: Tell user to verify with "Show dot-ai status"

For unreleased features: Build and use local images

If documenting a feature not yet in published charts:

bash

# Build MCP server image
npm run build
docker build -t dot-ai:test .
kind load docker-image dot-ai:test --name dot-test

# Build agentic-tools plugin image
docker build -t dot-ai-agentic-tools:test ./packages/agentic-tools
kind load docker-image dot-ai-agentic-tools:test --name dot-test

Add these flags to helm install:

--set image.repository=dot-ai \
--set image.tag=test \
--set image.pullPolicy=Never \
--set plugins.agentic-tools.image.repository=dot-ai-agentic-tools \
--set plugins.agentic-tools.image.tag=test \
--set plugins.agentic-tools.image.pullPolicy=Never

IMPORTANT: Always use

KUBECONFIG=./kubeconfig.yaml

for all kubectl/helm commands.

If any step fails or doesn't match existing docs: STOP and discuss whether to update those docs before proceeding.

Why fresh cluster? Ensures documentation examples work from a known clean state and validates setup docs.

务必从干净的测试集群开始，确保文档示例可复现。

遵循现有文档（
docs/setup/mcp-setup.md
）——以此验证文档的有效性。

Claude 直接使用 Bash 工具执行所有基础设施步骤：

如有现有测试集群，先将其拆除

bash

kind delete cluster --name dot-test 2>/dev/null || true
rm -f ./kubeconfig.yaml

创建全新的 Kind 集群并生成本地 kubeconfig

bash

kind create cluster --name dot-test --kubeconfig ./kubeconfig.yaml
export KUBECONFIG=./kubeconfig.yaml

安装前置依赖（ingress 控制器）

bash

kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/deploy/static/provider/kind/deploy.yaml
# Wait for ingress to be ready
kubectl wait --namespace ingress-nginx --for=condition=ready pod --selector=app.kubernetes.io/component=controller --timeout=300s

遵循 docs/setup/mcp-setup.md 文档操作（如果功能不需要控制器则跳过）
- 步骤1：设置环境变量（使用环境中已有的 API 密钥）
- 步骤2：通过 Helm 安装控制器（如果功能不需要则跳过）
- 步骤3：通过 Helm 安装 MCP 服务器
- 步骤4：告知用户配置 MCP 客户端
- 步骤5：告知用户通过“Show dot-ai status”命令验证

针对未发布功能：构建并使用本地镜像

如果要记录尚未发布到图表中的功能：

bash

# Build MCP server image
npm run build
docker build -t dot-ai:test .
kind load docker-image dot-ai:test --name dot-test

# Build agentic-tools plugin image
docker build -t dot-ai-agentic-tools:test ./packages/agentic-tools
kind load docker-image dot-ai-agentic-tools:test --name dot-test

在 Helm 安装命令中添加以下参数：

--set image.repository=dot-ai \\
--set image.tag=test \\
--set image.pullPolicy=Never \\
--set plugins.agentic-tools.image.repository=dot-ai-agentic-tools \\
--set plugins.agentic-tools.image.tag=test \\
--set plugins.agentic-tools.image.pullPolicy=Never

重要提示：所有 kubectl/helm 命令请始终使用

KUBECONFIG=./kubeconfig.yaml

。

如果任何步骤失败或与现有文档不符：请暂停并讨论是否需要先更新文档，之后再继续。

为什么使用全新集群？ 确保文档示例从已知的干净状态开始运行，同时验证安装文档的有效性。

Step 3: Outline the Documentation

步骤3：拟定文档大纲

Present an outline of sections to write. Example:

1. Overview (what it does, when to use it)
2. Prerequisites
3. Basic Usage (with real examples)
4. Advanced Features
5. API Reference
6. Troubleshooting
7. Next Steps

Get user confirmation on the outline before proceeding.

展示要编写的章节大纲。示例：

1. 概述（功能用途、适用场景）
2. 前置条件
3. 基础用法（含真实示例）
4. 高级功能
5. API 参考
6. 故障排查
7. 后续步骤

在继续编写前，请获取用户对大纲的确认。

Step 4: Write Chunk-by-Chunk

步骤4：分块编写

For each section:

Propose the section content - Brief description of what this section covers
Execute or request execution:
- Bash commands: Claude runs these directly using Bash tool
- MCP interactions: Ask user to send intent and share output (these are the user-facing examples we're documenting)
Wait for output - For MCP interactions, user shares the actual output
Write the chunk - Create the documentation section using real output
Apply the edit - Use Edit tool to add to the doc file
Proceed to next - Move to the next section

Key distinction: Infrastructure/setup = Claude runs it. User-facing MCP examples = User runs it and shares output.

针对每个章节：

提议章节内容 - 简要说明本章节涵盖的内容
执行或请求执行：
- Bash 命令：Claude 直接使用 Bash 工具运行这些命令
- MCP 交互：请求用户发送指令并分享输出（这些是我们要记录的面向用户的示例）
等待输出 - 对于 MCP 交互，用户分享实际输出
编写章节内容 - 使用真实输出创建文档章节
应用编辑 - 使用编辑工具将内容添加到文档文件中
进入下一章节 - 继续处理下一个章节

关键区别：基础设施/安装操作 = Claude 执行。面向用户的 MCP 示例 = 用户执行并分享输出。

Step 5: Cross-Reference Check

步骤5：交叉引用检查

After all sections are written:

Verify internal links work
Check links to other docs exist
Update
```
mcp-tools-overview.md
```
if adding a new tool guide
Update any index pages

所有章节编写完成后：

验证内部链接是否可用
检查是否存在指向其他文档的链接
如果添加了新工具指南，请更新
```
mcp-tools-overview.md
```
更新所有索引页面

Step 6: Final Review

步骤6：最终审核

Tell the user: "Documentation complete. Please review the full file and let me know if any adjustments are needed."

告知用户：“文档编写完成。请查看完整文件，如有需要调整的地方请告知。”

Example Execution Request Formats

示例执行请求格式

For MCP tool operations:

Please send this intent to your MCP client:
"Ingest this document into the knowledge base: [content] with URI: [url]"

Share the response you receive.

For status checks:

Please ask: "Show dot-ai status"

Share what you see for the Vector DB collections.

For bash commands:

Please run:
kubectl get pods -n dot-ai

Share the output.

针对 MCP 工具操作：

请将以下指令发送给你的 MCP 客户端：
"Ingest this document into the knowledge base: [content] with URI: [url]"

请分享你收到的响应。

针对状态检查：

请发送指令："Show dot-ai status"

请分享你看到的 Vector DB 集合信息。

针对 bash 命令：

请运行：
kubectl get pods -n dot-ai

请分享输出结果。

Important Rules

重要规则

Never invent output - Always use real responses from the user
Never skip validation - Every example must be executed first
Keep sections small - One concept per chunk for easy review
Use user language - Avoid internal/developer terminology
Include error cases - Document what happens when things go wrong

绝不编造输出 - 始终使用用户提供的真实响应
绝不跳过验证 - 每个示例都必须先执行
保持章节短小 - 每个章节只涵盖一个概念，便于审核
使用用户语言 - 避免使用内部/开发者术语
包含错误场景 - 记录出现问题时的情况

File Locations

文件位置

Feature guides:
```
docs/guides/mcp-*-guide.md
```
Setup guides:
```
docs/setup/*.md
```
Tool overview:
```
docs/guides/mcp-tools-overview.md
```
Images:
```
docs/img/
```

功能指南：
```
docs/guides/mcp-*-guide.md
```
安装指南：
```
docs/setup/*.md
```
工具概览：
```
docs/guides/mcp-tools-overview.md
```
图片：
```
docs/img/
```
",