中文技术文档写作规范与指南

"《中文技术文档写作风格指南》是一份详细指导如何撰写高质量中文技术文档的资源，由yikeke于2021年09月22日发布。该指南涵盖了语言风格、文档结构样式、内容元素、标点符号、命名规则以及拼写与语法等多个方面，旨在提升中文技术文档的可读性和一致性，降低沟通成本。 1. 关于本指南 本指南的目的是提高中文技术文档的可读性，统一文档风格，确保公司对外输出的形象一致，并减少因不同作者对同一问题的不同理解而产生的决策成本。它适用于所有编写中文文档的人员，如产品研发人员和技术作家。 2. 语言风格 - 对话式：鼓励使用亲切、友好的语言，使读者感觉更加亲近。 - 客观礼貌：保持专业的同时，避免使用过于主观或生硬的措辞。 - 简洁清晰：用最少的词汇传达最多的信息，避免冗余和复杂。 - 通俗易懂：使用常见词汇和简单句型，让广泛读者群体都能理解。 - 用户导向：始终考虑读者需求，以用户为中心进行写作。 - 用词恰当：选择最合适的词语来表达意思，避免歧义。 3. 文档结构样式 - 标题：清晰明确，层次分明，帮助读者快速定位信息。 - 段落：逻辑连贯，每段只讨论一个主题。 - 句子：简短有力，易于理解。 - 目录：提供完整的导航，方便查找。 4. 文档内容元素 - 空白符号：正确使用空格、换行等，增加阅读舒适度。 - 列表：有序或无序列表，用于组织信息，提高可读性。 - 表格：清晰呈现数据，便于比较和分析。 - 图形和图片：直观展示复杂概念，辅助文字说明。 - 注意和说明：突出重要提示，防止误解。 - 代码块和代码注释：规范代码展示，解释代码功能。 - 链接：提供更多信息来源，增强文档实用性。 - 引用：引用其他来源，保证信息准确性。 - 缩略语：定义并使用常见缩写，保持一致性。 - 数字：准确使用数字，避免模糊表述。 - 单位符号：遵循国际标准，正确使用单位。 5. 标点符号 - 常用中文标点：介绍并规范了各种中文标点的使用。 - 中文标点使用：详细讲解中文标点的规则和应用场景。 - 中英文混用标点：指导在混合语言环境下正确使用标点。 6. 名称与命名 - 文件命名：给出文件命名的最佳实践，以便于管理和查找。 - 产品命名：强调产品名称的独特性和识别性。 - 名称使用：统一命名规则，避免混淆。 7. 拼写与语法 - 拼写：确保单词拼写正确，减少错别字。 - 语法：遵循语法规则，确保句子结构完整。 8. 文档质量检查工具 - 提供一些可用于检查文档拼写、语法和风格的工具，以提升文档质量。 9. 参考资料 - 列出相关资料和进一步阅读的资源，供读者深入研究。 本指南鼓励所有从业者参与贡献、讨论和改编，以不断优化和更新，助力中文技术文档写作的标准化进程。"