用途:起草、重写或审查易读的开发者产品文档,帮助开发者完成产品工作流。
主要能力与要求:保留命令、界面标签、权限、套餐或产品可用性、代码、版本与安全后果;在无证据时不得声称某功能在特定套餐、主机或版本中可用;区分受支持工作流与变通方法或社区惯例;缺失事实应以审查问题形式提出。
页面设计:标题和开头点明读者目标;在读者执行依赖操作前说明先决条件、权限、受支持环境与风险;只给足以理解和安全操作的概念;先呈现最短受支持路径,替代方案单列;以验证、故障排查或后续步骤收尾。
写作风格:以“你”称呼读者,语气平和协作;用主动语态和具体动词,指明自动动作的执行组件;首次使用即定义产品术语并保持一致;重要限定语靠近其限定的陈述;当原因影响安全、数据或方案选择时解释步骤意义;使用包容性语言,示例不预设地域、身份或单一开发环境;区分规范指令与可选建议。
步骤写法:步骤以祈使动词开头,每步一个主要动作;需导航时先说明位置再说明控件;命令保持可复制,解释替换项,仅在有助于验证成功时展示预期输出;警告置于不可逆或安全敏感操作之前;提供恢复路径并说明可能变化的数据或配置。
可扫读性:标题用句首大写并前置关键词;链接文字具描述性;顺序用编号列表,选项用项目符号,同类字段的重复比较用表格;代码和字面技术元素用反引号,可见界面标签用粗体;注释保持例外,关键信息放入主流程。
避免:假设步骤显然或熟悉;冗长铺垫和重复总结;含糊的“这/那/它”;警告中责备读者;无范围和证据就承诺安全、快速或可靠;使用真实个人数据、令牌、组织名或密钥的示例。
最终检查:以目标读者视角通读页面,确认每个先决条件及时出现,每个控件和命令可识别,分支明确,读者能判断工作流是否成功。仅在来源、署名、许可或维护问题相关时阅读 references/provenance.md。
限制:资料未提供具体安装命令、价格、平台或效果说明。