dsh-doc-standards:文档写不下时,先查结构,别急着压字数

文档超过字数预算，最常见的处理是删。

先删例子，再删解释，把几段并成一句。CI 终于绿了，读者也终于不知道该从哪下手。

DeepSeek Harness 的 dsh-doc-standards 不把长度单独当缺陷。它要求先看文档放错地方没有、教程和参考是否混在一起、父文档是不是把子目录的内容又讲了一遍。结构理顺以后，才轮到压字数。

1. 一篇文档先要说清自己是什么

判断教程还是参考，不能只看文件名。

教程要带读者按顺序完成一件事，最后能看到结果。它应该交代前置条件、操作步骤、验证方式和容易踩的坑。参考文档供人查找，重点是边界、字段、默认值和完整范围，不必强行安排一条学习路线。

一篇文档前半段带着新人安装，后半段突然列完整配置表，就混了两种用途。dsh-doc-standards 会建议拆开，让教程链接到参考，而不是把所有内容都塞进一个长页面。

教程还要说明面向谁。初学者页面不能默认读者懂仓库内部术语，高级教程也不用从“什么是命令行”讲起。

2. 父文档和子文档各写多少

Skill 的层级规则^[1] 可以概括成三句话：

当前文档把自己的主题讲完整直接子项只做必要概览更深的细节留给对应子文档

例如一个“插件系统”总览应该讲插件在整体架构里的位置、共同生命周期和入口，再概括插件类型。某一种存储插件的配置字段、故障恢复和示例，放到它自己的页面。

父页面若把每个子系统都抄一遍，内容一更新就会出现多个版本。父页面若只列链接，又失去总览作用。这里要的是职责边界，不是越短越好。

3. 字数预算报警以后，按什么顺序处理

DeepSeek Harness 有文档预算校验。dsh-doc-standards 给出的处理顺序是：

relocate   把放错层级或混错用途的内容移走condense   删除重复，压缩仍属本页的表达raise      内容确有必要，再提高预算

若先删字，完整说明很容易被削成摘要；先提高预算，又会把结构问题藏起来。

移动文件之前还要搜入站链接，双语文档要连同 counterpart 和配对记录一起改。生成目录、目录清单等派生内容不能手工修。一次“整理文档”因此可能涉及链接、翻译和构建，不能只看那一个 Markdown 文件。

4. 它也管一种常见的文档虚胖

有些文档很长，因为把写作过程留在正文里：

根据前面的讨论，我们决定……这次 PR 新增了……为了回应审查意见，这里补充……

这些话对当时的作者有上下文，对半年后的读者常常没有。dsh-doc-standards^[1] 会把这类问题交给 dsh-trim-cot-leakage 进一步检查，把仍然成立的事实改成当前状态，把写作过程删掉。

手写目录也要尽量换成权威数据源。包列表、配置项和事件名若能由代码生成，就别在三篇文档里各维护一份。

5. 怎么用

可以把 DeepSeek Harness 仓库^[2] 交给 AI，再指定要整理的文档：

请按 dsh-doc-standards 审查这组文档。先判断每篇的用途、读者和层级职责，再找教程与参考混写、父子重复和手工清单。遇到字数超限，按 relocate、condense、raise 的顺序给方案。先列移动计划和受影响链接，不要直接删内容。

它是为这个仓库写的，具体命令和双语规则未必适合所有项目。文档类型、层级职责和预算处理顺序倒很容易移植。

6. 自己写一个文档 Skill

先给每类文档定义“读者来这里要做什么”。教程、参考、架构说明、决策记录，各自列出必须回答的问题。

再写父子层级规则，明确总览页讲到哪一层。最后加预算和移动检查：超限先查错位；改名先查入站链接；有多语言就一起改；生成文件不手修。

最小版本甚至不需要脚本。一张审查表配合 rg 查链接，已经比“把这篇压到两千字”靠谱。等目录稳定，再把字数、链接和配对关系放进 CI。

7. 我的判断

长文档有时确实啰嗦，有时只是替三篇文档干了活。两种情况看起来都超长，治法完全不同。

dsh-doc-standards 先问用途和位置，再动句子。这比把编辑工作交给字数计数器慢一点，可读者最终得到的是一套能走通的文档，而不是一份刚好没超过红线的压缩包。