write-openspec-docs

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Write OpenSpec docs

撰写OpenSpec文档

You are now writing OpenSpec's user docs. Read writing.md; it is the style authority for everything drafted here. The short version, in effect immediately:

A page is a retrieval surface, not an essay. Structure decides whether the reader finds the answer; prose only decides how it reads. Open every section with the answer, never a running story.
Choose the page type before the outline. Guides follow the reader's task; reference mirrors the product's structure and uses exact field, command, and file names as scan anchors. Reference needs complete coverage without compressing several facts into one sentence, cell, or paragraph.
Draft the shortest version that answers; expanding a spare page is cheap, cutting a bloated one is a rewrite. Plain words, the fewest of them: an idea that fits in one line takes one line. Depth most readers skip goes behind a link, and the payload (commands, real output, failures and fixes) stays whole.
Dumb sentences, smart structure. Write the obvious sentence (actor, verb, object, stating the literal event); never compress extra facts in or take an angle. No hype adjectives, no preamble, no em dashes.
One job per slot: one fact per sentence, list intros only announce the list, one reader question or lookup target per section. A related fact gets its own slot, never a ride in someone else's.
Ground items in what the reader can verify: path or folder first, concept as the gloss, real output shown honestly.
No house template. Inventories open with a list naming every item, then expand each in its own unit after the list, never inline. Sequences take numbered steps (numbers mean order; inventories take bullets). Single ideas and reasoning stay in short prose.
Every load-bearing fact sits on a scan anchor: code fence, numbered bold lead-in,
```
**Term**: fact
```
bullet, table, file tree. Never only mid-paragraph.
Before finishing, run two backstop tests. Retrievability: can each question or exact product name be found by scanning alone? The glance: inspect the rendered page as shapes; does it look finishable, or like work? Check table-heavy changes at desktop and narrow widths. A failure means a slot got written without being earned; fix it now, don't leave it for review.

您现在正在撰写OpenSpec的用户文档。请阅读writing.md；它是所有在此撰写内容的风格权威。以下是立即生效的精简版规则：

文档页面是信息检索载体，而非散文。结构决定读者能否找到答案；措辞仅影响阅读体验。每个章节开头直接给出答案，切勿铺垫叙述。
先确定页面类型，再构建大纲。指南类文档遵循读者的任务流程；参考类文档镜像产品结构，并使用精确的字段、命令和文件名作为浏览锚点。参考类文档需完整覆盖内容，切勿将多个信息压缩到一个句子、单元格或段落中。
先撰写能回答问题的最简版本；扩充简洁的页面成本低，删减臃肿的页面则相当于重写。使用平实且最少的文字：能用一行表达的想法就只用一行。多数读者会跳过的深度内容放在链接后，核心内容（命令、真实输出、问题与修复方案）保持完整呈现。
语句直白，结构清晰。撰写直白的句子（主语、谓语、宾语，陈述字面事实）；切勿额外添加信息或带有倾向性。禁用浮夸形容词、开场白和破折号。
每个单元只承担一项任务：每句表达一个事实，列表引言仅用于介绍列表，每个章节对应一个读者的问题或检索目标。相关事实需单独成单元，切勿依附于其他内容。
内容基于读者可验证的信息：先给出路径或文件夹，再解释概念，如实展示真实输出。
无固定模板。清单类内容先以列表列出所有条目，再在列表后逐个展开介绍，切勿内联展开。流程类内容使用编号步骤（编号代表顺序；清单类使用项目符号）。单一观点和说明性内容用简短文字呈现。
每个关键信息都需搭配浏览锚点：代码块、加粗编号开头、
```
**术语**: 事实
```
项目符号、表格、文件树。切勿仅放在段落中间。
完成前，进行两项最终检查。检索性检查：仅通过浏览能否找到每个问题或确切的产品名称？视觉检查：查看渲染后的页面布局；看起来是已完成状态，还是仍需完善？同时检查表格较多的内容在桌面端和窄屏宽度下的显示效果。若未通过检查，说明某个单元的撰写不合理，请立即修正，不要留到审核阶段。

Ground rules

基本规则

Load the
```
no-ai-slop
```
skill before drafting; it owns the generic slop patterns, while writing.md owns what OpenSpec's docs specifically look and sound like.
Read the target page in full before editing it.
Real facts only: flags, paths, and output as they exist in source. If a claim can't be checked cheaply, still write it, but name it as unchecked when you show the work; never bridge a gap with a plausible-sounding sentence.
A fact lives on one page; everywhere else links to it. The docs tree's README owns the page map and structural invariants; check it before restructuring or adding pages.
For reference pages, inventory the contract from source before drafting prose. Follow the reference process in writing.md.
When unsure how something should scan or sound, match the exemplars:
```
docs-lab/start/setup.md
```
for section shape and inventories,
```
docs-lab/start/installation.md
```
(Uninstalling) for multi-step tasks.

撰写前加载
```
no-ai-slop
```
技能；它负责处理通用的冗余内容模式，而writing.md则定义了OpenSpec文档特有的外观和风格。
编辑目标页面前，请完整阅读该页面。
仅使用真实信息：标志、路径和输出需与源代码一致。若某项声明无法快速验证，仍可撰写，但需在展示内容时注明未验证；切勿用看似合理的句子填补信息缺口。
每个事实仅出现在一个页面；其他地方均链接至该页面。文档树的README负责页面地图和结构规范；调整结构或添加页面前，请先查看该文件。
对于参考类页面，撰写文字前先从源代码中整理出完整的约定内容。遵循writing.md中的参考文档撰写流程。
若不确定内容的浏览效果或风格，请参考示例：
```
docs-lab/start/setup.md
```
（章节结构和清单示例）、
```
docs-lab/start/installation.md
```
（卸载部分，多步骤任务示例）。

When done

完成后

Show the user what changed and name any unchecked claims.

If the user asks for the deep, evidence-first drafting session (run every command, one section per sitting, formal checkpoints), follow full-process.md.

向用户展示修改内容，并注明所有未验证的声明。

如果用户要求进行深度、以证据为先的撰写环节（运行所有命令，每次撰写一个章节，设置正式检查点），请遵循full-process.md。