From 7effba36ff1e6bab4f65620a72f799d738297fc0 Mon Sep 17 00:00:00 2001 From: 7Wate Date: Tue, 8 Mar 2022 10:25:59 +0800 Subject: [PATCH] =?UTF-8?q?=E6=A0=87=E5=87=86=EF=BC=9A=E6=8A=80=E6=9C=AF?= =?UTF-8?q?=E6=96=87=E6=A1=A3=EF=BC=88=E7=AE=80=E4=BB=8B=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/标准/技术文档/简介.md | 53 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 53 insertions(+) create mode 100644 docs/标准/技术文档/简介.md diff --git a/docs/标准/技术文档/简介.md b/docs/标准/技术文档/简介.md new file mode 100644 index 00000000..4c967a19 --- /dev/null +++ b/docs/标准/技术文档/简介.md @@ -0,0 +1,53 @@ +--- +id: 简介 +title: 简介 +sidebar_position: 1 +data: 2022年3月8日 +--- + +本指南规范了一种中文写作风格，主要用于技术文档的编写。素材来源于互联网，为各家中文文案风格指南的综合，旨在对中文技术文档的**语言风格、结构样式、内容元素、标点符号、格式排版**等方面给出参考规范。 + +> **引用者注：** +> +> 本篇系列文档引用自 yikeke 的开源项目《[中文技术文档写作风格指南](https://github.com/yikeke/zh-style-guide)》 +> +> 本人进行了**二次修改**便于自己使用，**感谢原作者的开源奉献！** +> +> **作者注：** +> +> - 本指南只提供参考规范，不提供权威标准。一些规范在业界并无定论，争议点作者会以建议形式给出。 +> - 本指南欢迎所有业界同仁们贡献、讨论、改编。 +> - 本指南保持更新，欢迎任何人提出改进意见，如发现有错误或遗漏的点，请提 [Issue](https://github.com/yikeke/zh-style-guide/issues/new)。 + +希望本指南的出现能为日后业界标准的建立贡献一点力量。 + +## 目的 + +- 提高中文文案的可读性 +- 统一文档风格，保证公司对外输出形象一致 +- 避免不同的文档作者对同一问题反复作出决策，降低与文档相关的沟通成本 + +## 适用范围 + +- 为编写中文文档的作者（如产品研发人员、tech writer 等）提供规范或建议 +- 审校文档过程中争议问题的裁决 +- 也可供软件界面、帮助文档等资料开发人员参考 + +## 使用原则 + +本指南是一本查询手册，建议初次阅读本指南时，先大致浏览目录章节结构，了解本指南涵盖的内容范围；之后就编写文档时碰到的实际问题，再回头查找相应规范。 + +## 用词说明 + +本指南使用的表示“要求”的全部关键词已在下表第二列列出，具体释义请参见 [RFC2119](https://tools.ietf.org/html/rfc2119) 对相应词语做出的相关规定： + +| RFC2119 中定义的关键词 | 对应的中文关键词 | 释义说明 | +| -------------------------- | --------------------------- | ------------------------------------------------------------ | +| MUST/REQUIRED/SHALL | 强制/必须/务必/只能 | 强制性规则，表示绝对要求这样做 | +| MUST NOT/SHALL NOT | 禁止/不能/不要 | 强制性规则，表示绝对禁止这样做 | +| SHOULD/RECOMMENDED | 应/应当/应该/建议/推荐 | 非强制性规则，表示一般情况下应该这样做，但在知悉全部后果的前提下，可以选择不这样做 | +| SHOULD NOT/NOT RECOMMENDED | 不应当/不应该/不建议/不推荐 | 非强制性规则，表示一般情况下不应该这样做，但在知悉全部后果的前提下，可以选择这样做 | +| MAY/OPTIONAL | 可以/可选 | 非强制性规则，表示这个要求是可选的，可以这样做，也可以不这样做 | + +> RFC (Request For Comments) 指关于互联网标准的正式文件，在这些文件的表述过程中，必须严格区分哪些是"建议" (suggestion)，哪些是"要求" (requirement)。所以，RFC2119 专门对五个关键词的涵义作出了规定，分别表示"要求"的严格程度。 +