用途:创建全面的风格指南,确保技术文档在一致性、清晰度和质量上达到统一标准。适用场景包括建立写作规范、保证术语一致、新写作者入职、维护文档质量、定义术语、设定语气、制作模板以及规模化文档生产。
主要能力:提供风格指南的结构框架,覆盖语气(专业、有帮助、清晰)、角度(第二人称、主动语态)、写作原则(清晰、简洁、一致、准确)、语法与格式规则(标题句首大写、列表使用牛津逗号、少用感叹号与缩写)、术语表(如推荐 click 而非 click on,sign in 而非 login)以及代码示例规范(语法高亮、完整可运行示例、注释、预期输出)。同时给出正反例对比,说明如何避免过于随意、被动语态和不专业表达。
最佳实践:建立适用于所有场景的清晰规则,把风格指南作为持续更新的活文档,以示例驱动而非单纯说教,鼓励团队协作输入,放在易获取的位置,集成 linter 与拼写检查工具,作为入职培训材料,并用版本控制跟踪变更。
资源:参考 Google 开发者文档风格指南、Microsoft 写作风格指南,以及 Vale linter 用于风格指南执行。
限制:资料未提供具体安装命令、价格、支持平台或与其他工具的集成步骤,相关内容暂未提供。