关于本指南

本指南为中文技术文档的编写提供了一套风格指南规范。作者综合了在互联网上能找到的各家中文文案风格指南,在中文技术文档的语言风格、结构样式、内容元素、标点符号、格式排版等方面给出参考规范。

作者注:

  • 本指南只提供参考规范,不提供权威标准。一些规范在业界并无定论,有争议的点作者会以建议形式给出。

  • 本指南欢迎所有业界同仁们贡献、讨论、改编。

  • 本指南保持更新,欢迎任何人提出改进意见,如发现有错误或遗漏的点,请提 Issue

希望本指南的出现能为日后业界标准的建立贡献一点力量。

目的

  • 提高中文文案的可读性

  • 统一文档风格,保证公司对外输出形象一致

  • 避免不同的文档作者对同一问题反复作出决策,降低与文档相关的沟通成本

适用范围

  • 为编写中文文档的作者(如产品研发人员、tech writer 等)提供规范或建议

  • 审校文档过程中争议问题的裁决

  • 也可供软件界面、帮助文档等资料开发人员参考

使用原则

本指南为查询手册性质,建议初次阅读本指南时,先大致浏览目录章节结构,了解本指南涵盖的内容范围。之后实际编写文档时碰到相应问题时,再回来查找相应规范。

用词说明

本指南使用的表示“要求”的全部关键词已在下表第二列列出,具体释义请参见 RFC2119 对相应词语做出的相关规定:

RFC2119 中定义的关键词 对应的中文关键词 释义说明
MUST/REQUIRED/SHALL 强制/必须/务必/只能 强制性规则,表示绝对要求这样做
MUST NOT/SHALL NOT 禁止/不能/不要 强制性规则,表示绝对禁止这样做
SHOULD/RECOMMENDED 应/应当/应该/建议/推荐 非强制性规则,表示一般情况下应该这样做,但在知悉全部后果的前提下,可以选择不这样做
SHOULD NOT/NOT RECOMMENDED 不应当/不应该/不建议/不推荐 非强制性规则,表示一般情况下不应该这样做,但在知悉全部后果的前提下,可以选择这样做
MAY/OPTIONAL 可以/可选 非强制性规则,表示这个要求是可选的,可以这样做,也可以不这样做

RFC (Request For Comments) 指关于互联网标准的正式文件,在这些文件的表述过程中,必须严格区分哪些是”建议” (suggestion),哪些是”要求” (requirement)。所以,RFC2119 专门对五个关键词的涵义作出了规定,分别表示”要求”的严格程度。

贡献列表

此列表汇总了本指南的所有贡献者名单。

欢迎在 GitHub 上提交 Pull Request 进行贡献。

贡献者 总提交贡献数 First Commit
yikeke (Author) 2020-09-14
CharLotteiu 13 2020-09-14
oldLady344 4 2020-10-05
jtr109 3 2020-11-09
techkang 1 2020-11-06