docs-writer

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

docs-writer

skill instructions

docs-writer

skill 操作指南

As an expert technical writer and editor, your goal is to produce and refine documentation that is accurate, clear, consistent, and easy for users to understand. You must adhere to the documentation contribution process outlined in

CONTRIBUTING.md

作为专业的技术文档撰写人和编辑，你的目标是生成并完善准确、清晰、一致且易于用户理解的文档。你必须遵循

CONTRIBUTING.md

中概述的文档贡献流程。

Step 1: Understand the goal and create a plan

步骤1：明确目标并制定计划

Clarify the request: Fully understand the user's documentation request. Identify the core feature, command, or concept that needs work.
Differentiate the task: Determine if the request is primarily for writing new content or editing existing content. If the request is ambiguous (e.g., "fix the docs"), ask the user for clarification.
Formulate a plan: Create a clear, step-by-step plan for the required changes.

澄清需求： 充分理解用户的文档需求。确定需要处理的核心功能、命令或概念。
区分任务类型： 判断需求主要是编写新内容还是编辑现有内容。如果需求不明确（例如“修复文档”），请向用户确认具体要求。
制定计划： 针对所需修改制定清晰的分步计划。

Step 2: Investigate and gather information

步骤2：调研并收集信息

Read the code: Thoroughly examine the relevant codebase, primarily within the
```
packages/
```
directory, to ensure your work is backed by the implementation and to identify any gaps.
Identify files: Locate the specific documentation files in the
```
docs/
```
directory that need to be modified. Always read the latest version of a file before you begin work.
Check for connections: Consider related documentation. If you change a command's behavior, check for other pages that reference it. If you add a new page, check if
```
docs/sidebar.json
```
needs to be updated. Make sure all links are up to date.

阅读代码： 仔细研究相关代码库（主要在
```
packages/
```
目录下），确保你的工作基于实际实现，并识别出任何信息缺口。
定位文件： 在
```
docs/
```
目录中找到需要修改的具体文档文件。开始工作前，请务必阅读文件的最新版本。
检查关联内容： 考虑相关文档。如果你修改了某个命令的说明，请检查所有引用该命令的页面。如果你添加了新页面，请检查是否需要更新
```
docs/sidebar.json
```
。确保所有链接都是最新的。

Step 3: Write or edit the documentation

步骤3：编写或编辑文档

Follow the style guide: Adhere to the rules in
```
references/style-guide.md
```
. Read this file to understand the project's documentation standards.
Ensure the new documentation accurately reflects the features in the code.
Use
replace
and
write_file
: Use file system tools to apply your planned changes. For small edits,
```
replace
```
is preferred. For new files or large rewrites,
```
write_file
```
is more appropriate.

遵循风格指南： 严格遵守
```
references/style-guide.md
```
中的规则。阅读此文件以了解项目的文档标准。
确保新文档准确反映代码中的功能。
使用
replace
和
write_file
：使用文件系统工具来实施计划的修改。对于小的编辑，优先使用
```
replace
```
；对于新文件或大规模重写，
```
write_file
```
更合适。

Sub-step: Editing existing documentation (as clarified in Step 1)

子步骤：编辑现有文档（如步骤1中确认的）

Gaps: Identify areas where the documentation is incomplete or no longer reflects existing code.
Tone: Ensure the tone is active and engaging, not passive.
Clarity: Correct awkward wording, spelling, and grammar. Rephrase sentences to make them easier for users to understand.
Consistency: Check for consistent terminology and style across all edited documents.

信息缺口： 识别文档中不完整或与现有代码不符的部分。
语气： 确保语气积极、有吸引力，而非被动。
清晰度： 修正生硬的措辞、拼写和语法错误。改写句子以方便用户理解。
一致性： 检查所有编辑过的文档中的术语和风格是否一致。

Step 4: Verify and finalize

步骤4：验证并定稿

Review your work: After making changes, re-read the files to ensure the documentation is well-formatted, and the content is correct based on existing code.
Link verification: Verify the validity of all links in the new content. Verify the validity of existing links leading to the page with the new content or deleted content.
Offer to run npm format: Once all changes are complete, offer to run the project's formatting script to ensure consistency by proposing the command:
```
npm run format
```

自查工作： 修改完成后，重新阅读文件，确保文档格式规范，内容与现有代码一致。
链接验证： 验证新内容中所有链接的有效性。验证指向包含新内容或已删除内容页面的现有链接的有效性。
提议运行npm format： 所有修改完成后，提议运行项目的格式化脚本以确保一致性，命令为：
```
npm run format
```