用途:这是一个面向 Web 平台文档的写作与审查技能,用于起草、改写或审计 HTML、CSS 等 Web 技术文档。其目标是把 Web 平台解释得足够清楚,让读者能把知识迁移到单个复制示例之外。
主要能力与原则:保留平台事实,保持语法、取值、异常、标准状态、浏览器行为和代码准确;区分规范要求与观察到的实现行为;不推断兼容性,需请求或链接权威兼容性数据;已知的实验性、已弃用和非标准特性要明确标注。写作前设定受众与页面目的,选择读者水平并列出页面预设知识,确定以参考、指南、教程还是概念解释为主,先说明特性是什么以及开发者为何使用,再展开细节。参考信息按可预测顺序排列,学习内容从可用的心智模型到有用示例再到边界情况;前置知识用链接而非重讲。
表达与示例:使用清晰、简洁、一致的术语,一句一个主要观点,在有助于明确动作主体时用主动语态;先定义陌生术语再依赖它;解释代码做什么以及关键行为何重要,不逐词叙述;示例用于揭示行为、参数和边界情况,而非装饰;说明文档结构、安全上下文、网络状态或浏览器支持方面的假设;使用包容、字面的语言。示例取仍能展示真实行为的最小版本,包含全部必要设置或明确标注省略的脚手架,使用安全占位数据和可访问标记,保持 HTML、CSS、JavaScript 与正文中的命名一致,说明预期结果和常见失败。
格式与避免事项:标题用句首大写并描述该节信息;元素、属性、方法、取值和代码用反引号;顺序步骤用编号列表,独立标准用项目符号;注释少用,正确使用所需事实放在正文;规范性细节重要时链接相关规范或权威来源。避免假设读者知道缩写、API 家族或编程模式,避免称特性容易、明显或简单,避免掩盖主要用途的过度细节,避免依赖未声明全局状态的示例,避免把观点、建议、规范与浏览器行为混为一条主张,避免用不同术语重复同一定义。最后检查引言是否说明特性与用途、前置条件是否匹配受众、示例是否在所述上下文中可运行、术语是否一致、事实主张是否与建议分开。
限制:资料未提供具体安装命令、收费、价格、平台或效果信息;references/provenance.md 仅用于来源、归属、许可或维护问题。