code-sample-documentation

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Code Sample Documentation

代码样例文档

Use this skill to create and review code samples that are useful, accurate, copyable, and maintainable. It applies to executable examples, explanatory snippets, API request/response pairs, CLI commands, config files, and generated references.

This skill is derived from Docs for Developers: An Engineer's Field Guide to Technical Writing, especially Chapter 5, "Integrating code samples." The guidance is transformed and paraphrased; do not copy book prose into user outputs. Source: https://link.springer.com/book/10.1007/978-1-4842-7217-6

使用本技能创建和评审实用、准确、可复制且易于维护的代码样例。它适用于可执行示例、解释性代码片段、API请求/响应对、CLI命令、配置文件以及生成的参考文档。

本技能源自《Docs for Developers: An Engineer's Field Guide to Technical Writing》（《开发者文档：技术写作工程师实用指南》），尤其是第5章“整合代码样例”。本指南是对原书内容的转化和改写；请勿将书中原文复制到用户输出中。来源：https://link.springer.com/book/10.1007/978-1-4842-7217-6

Quick Start

快速开始

Load
```
guidelines.md
```
to choose the smallest useful reference set.
Classify the sample as executable, explanatory, or paired request/response.
Check whether the sample is explained, concise, clear, usable, and trustworthy.
Use
```
workflows/review-code-sample.md
```
for a full sample review.
Prefer running or testing samples when feasible; otherwise mark what remains unverified.

加载
```
guidelines.md
```
以选择最小的实用参考集。
将样例分类为可执行型、解释型或请求/响应配对型。
检查样例是否具备清晰的解释、简洁性、易懂性、可用性和可信度。
使用
```
workflows/review-code-sample.md
```
进行完整的样例评审。
尽可能优先运行或测试样例；否则标记未验证的部分。

Default Output

默认输出

When reviewing or designing code samples, return:

Sample purpose - what the reader should learn or accomplish.
Sample type - executable, explanatory, request/response, CLI, config, or generated.
Issues or design notes - ordered by reader risk.
Revised sample - concise and copyable when requested.
Testing plan - how to verify runtime behavior, outputs, and version assumptions.
Maintenance notes - source of truth, owner, and generated/manual boundary.

在评审或设计代码样例时，返回以下内容：

样例用途 - 读者应学习或完成的内容。
样例类型 - 可执行型、解释型、请求/响应型、CLI、配置或生成型。
问题或设计说明 - 按读者面临的风险排序。
修订后的样例 - 按需提供简洁且可复制的版本。
测试计划 - 如何验证运行时行为、输出和版本假设。
维护说明 - 真实来源、负责人以及自动生成/手动编写的界限。

Need	Start Here
Understand sample types	`references/core/knowledge.md`
Apply sample rules	`references/core/knowledge.md`
See before/after examples	`references/core/knowledge.md`
Review or design a sample	`workflows/review-code-sample.md`
Route by task	`guidelines.md`

需求	起始位置
了解样例类型	`references/core/knowledge.md`
应用样例规则	`references/core/knowledge.md`
查看前后示例	`references/core/knowledge.md`
评审或设计样例	`workflows/review-code-sample.md`
按任务选择路径	`guidelines.md`

Core Posture

核心原则

A sample is documentation and software; treat it as both.
Match sample complexity to the reader's stage.
Make placeholders, inputs, outputs, and limitations explicit.
Do not imply a sample is production-ready unless it has been reviewed and tested for that use.

样例既是文档也是软件；需同时兼顾两者属性。
样例复杂度需匹配读者的学习阶段。
明确标注占位符、输入、输出和限制条件。
除非样例经过针对生产环境的评审和测试，否则不得暗示其可直接用于生产环境。