用途:起草、改写或审查简洁的产品与工程文档,使其成为可信的事实来源。
主要能力:保留技术事实,命令、代码、产品名、界面标签、版本、默认值与结果保持原样;不把实现细节写成产品承诺;区分已确认行为与变通方法、假设或计划行为;缺失的可用性、权限或版本信息应询问而非编造。
主题类型:每个主题只选一个主要目的——概念(说明是什么、为何重要、各部分关系)、任务(通过有序操作达成一个结果)、参考(以可预测结构呈现字段、选项、语法或限制)、故障排除(把症状连接到检查、原因与恢复)。目的冲突时拆分页面。
写作视角:从读者可完成或需知的内容开头;用户操作称“你”,产品执行动作时点名 GitLab 或其他组件;优先主动语态;每个功能保持一个术语并匹配产品可见标签与大小写;陈述事实与可实现结果,限定性能或安全声明;为翻译写作,使用明确主语、字面语言与直接语序。
任务与故障排除:前置条件、权限与可用性放在步骤前;步骤以祈使动词开头且每步可观察;动作后说明预期结果;配置变更不立即可见时加入验证;失败时先写读者看到的症状,再按成本从低到高给出检查,并说明恢复后果。使用假数据与保留示例域名,绝不暴露真实凭据。
格式:标题用句首大写,关键词靠前;代码、文件名、参数、值、短输出与错误用反引号;仅可见界面标签用粗体;序列用有序列表,独立项用无序列表;优先两句而非分号或重括号句。
避免:营销文案、未解释的最高级与保证收益;读者直接动作更清晰时用 allow 或 enable;easy、easily、simple、obvious 等难度判断;自我指涉式预告;指代不明时用 it、this、they;装饰性同义词、习语、文化引用与未来承诺;在一个流程中混合作者工作流、产品工作流与用户工作流。
最终检查:确认搜索词出现在标题与标题中,每个主题只有一个目的,前置条件完整,每项声明可支持;删除仅为引出下一句而存在的句子。仅在来源、归属、许可或维护问题时可读 references/provenance.md。
限制:资料未提供具体安装命令、收费、价格、平台或效果信息。