Skip to content

Commit 9e9ca29

Browse files
CharLotteiuCharLotteiu
committed
init
1 parent ea76147 commit 9e9ca29

File tree

126 files changed

+22593
-0
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

126 files changed

+22593
-0
lines changed

‎Makefile

+20
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
# Minimal makefile for Sphinx documentation
2+
#
3+
4+
# You can set these variables from the command line, and also
5+
# from the environment for the first two.
6+
SPHINXOPTS ?=
7+
SPHINXBUILD ?= sphinx-build
8+
SOURCEDIR = source
9+
BUILDDIR = build
10+
11+
# Put it first so that "make" without argument is like "make help".
12+
help:
13+
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
14+
15+
.PHONY: help Makefile
16+
17+
# Catch-all target: route all unknown targets to Sphinx using the new
18+
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
19+
%: Makefile
20+
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

‎build/doctrees/environment.pickle

19.5 KB
Binary file not shown.

‎build/doctrees/hello.doctree

2.22 KB
Binary file not shown.

‎build/doctrees/index.doctree

5.23 KB
Binary file not shown.

‎build/doctrees/world.doctree

2.47 KB
Binary file not shown.

‎build/doctrees/中文风格指南/关于本指南.doctree

14.9 KB
Binary file not shown.

‎build/doctrees/中文风格指南/语言风格.doctree

32 KB
Binary file not shown.

‎build/doctrees/关于本指南.doctree

13.5 KB
Binary file not shown.

‎build/doctrees/关于本指南/关于本指南.doctree

13.5 KB
Binary file not shown.

‎build/doctrees/关于本指南/目的.doctree

3.46 KB
Binary file not shown.

‎build/doctrees/目的.doctree

3.45 KB
Binary file not shown.

‎build/html/.buildinfo

+4
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
# Sphinx build info version 1
2+
# This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
3+
config: aaf28dcd1d033b6188e40346c3756840
4+
tags: 645f666f9bcd5a90fca523b33c5a78b7

‎build/html/_sources/hello.md.txt

+3
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
# hello world
2+
3+
### test markdown

‎build/html/_sources/hello.rst.txt

+2
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
hello
2+
=============

‎build/html/_sources/index.rst.txt

+25
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
.. PingCAP ZH styleguide documentation master file, created by
2+
sphinx-quickstart on Wed Sep 16 11:46:34 2020.
3+
You can adapt this file completely to your liking, but it should at least
4+
contain the root `toctree` directive.
5+
6+
Welcome to PingCAP ZH styleguide's documentation!
7+
=================================================
8+
9+
.. toctree::
10+
:maxdepth: 2
11+
:numbered:
12+
13+
中文风格指南/关于本指南
14+
中文风格指南/语言风格
15+
16+
:caption: Contents:
17+
18+
19+
20+
Indices and tables
21+
==================
22+
23+
* :ref:`genindex`
24+
* :ref:`modindex`
25+
* :ref:`search`

‎build/html/_sources/world.md.txt

+3
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
# hello world
2+
3+
### test markdown

‎build/html/_sources/中文风格指南/关于本指南.md.txt

+38
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
# 关于本指南
2+
3+
本指南为中文技术文档的编写提供了一套风格指南规范。作者综合了在互联网上能找到的各家中文文案风格指南，尝试在中文技术文档的**语言风格、结构样式、内容元素、标点符号、格式排版**等方面给出建议。
4+
5+
## 目的
6+
7+
- 提高中文文案的可读性
8+
- 避免文档工程师们对同一问题反复作出决策，降低团队成员之间的沟通成本
9+
- 帮助一个公司的文档团队统一文档风格，保证公司对外输出形象一致
10+
11+
## 适用范围
12+
13+
- 编写中文技术文档的文档工程师
14+
- 需要参与编写技术文档的产品研发人员
15+
- 审校文档过程中争议问题的裁决
16+
- 也可供软件界面、帮助文档等资料开发人员参考
17+
18+
## 使用原则
19+
20+
- 本指南只提供参考规范，不提供权威标准。事实上，本指南提出的一些规范在业界并无定论，有争议的点作者会以建议形式给出。
21+
- 本指南不是为了提供绝对正确的风格指南标准，而是在为日后业界建立标准铺路。
22+
- 本指南目前还只是建议版本，供所有从业者参与讨论。
23+
- 本指南将保持更新，欢迎任何人提出改进意见，如发现有错误或遗漏的点，请联系作者。
24+
25+
## 用词说明
26+
27+
本指南使用的表示“要求”的全部关键词已在下表第二列列出，具体释义请参见 [RFC2119](https://tools.ietf.org/html/rfc2119) 对相应词语做出的相关规定：
28+
29+
| RFC2119 中定义的关键词 | 对应的中文关键词 | 释义说明 |
30+
| -------------------------- | --------------------------- | ------------------------------------------------------------ |
31+
| MUST/REQUIRED/SHALL | 强制/必须/务必/只能 | 强制性规则，表示绝对要求这样做 |
32+
| MUST NOT/SHALL NOT | 禁止/不能/不要 | 强制性规则，表示绝对禁止这样做 |
33+
| SHOULD/RECOMMENDED | 应/应当/应该/建议/推荐 | 非强制性规则，表示一般情况下应该这样做，但在知悉全部后果的前提下，可以选择不这样做 |
34+
| SHOULD NOT/NOT RECOMMENDED | 不应当/不应该/不建议/不推荐 | 非强制性规则，表示一般情况下不应该这样做，但在知悉全部后果的前提下，可以选择这样做 |
35+
| MAY/OPTIONAL | 可以/可选 | 非强制性规则，表示这个要求是可选的，可以这样做，也可以不这样做 |
36+
37+
注：RFC (Request For Comments) 指关于互联网标准的正式文件，在这些文件的表述过程中，必须严格区分哪些是"建议" (suggestion)，哪些是"要求" (requirement)。所以，RFC2119 专门对五个关键词的涵义作出了规定，分别表示"要求"的严格程度。
38+

‎build/html/_sources/中文风格指南/语言风格.md.txt

+127
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,127 @@
1+
# 语言风格
2+
3+
本章对技术文档中使用的语言风格作出了统一规范。
4+
5+
## 对话式
6+
7+
技术文档中应使用对话式的、平易近人的语气。由于技术文档传达的技术信息本身已经较为枯燥难懂，因此不建议使用过于正式、无聊乏味的语气。
8+
9+
使用对话式的语气并不意味着完全用日常说话的方式来写文档。一般而言，口语存在冗长啰嗦、缺乏逻辑性的倾向，在编写技术文档时应极力避免该问题。
10+
11+
## 客观礼貌
12+
13+
技术文档中应保持客观礼貌的语气，这样最容易拉近与读者的距离。具体要求有：
14+
15+
● 应该客观地传达技术信息，而不是在推销产品，否则容易引起读者的反感。
16+
17+
● 保持一种友好礼貌的语气，不能显得强硬粗鲁、咄咄逼人。
18+
19+
● 不要穿插太多玩笑，让文档风格变得过分轻浮搞笑。偶尔滑稽一次是可取的，这样能适当展现作者或组织的个性，使人印象深刻。但必须记住，技术文档的首要目的是向读者传达技术信息，不能为了追求轻松愉快的文档风格而使读者不明所以。
20+
21+
## 简洁清晰
22+
23+
技术文档中应使用精练的语言。建议将文档中所有对表达意思没有明显作用的字、词、句删去，在不影响表达效果的前提下把文案长度减到最短。具体要求有：
24+
25+
● 禁止啰嗦冗长
26+
27+
● 禁止逻辑混乱
28+
29+
● 同一文档中勿重复表达同一事物
30+
31+
● **多用主动时态，尤其要阐述清楚主语和宾语**
32+
33+
## 通俗易懂
34+
35+
技术文档中不推荐使用只有特定人群才了解的语词。具体要求有：
36+
37+
● 不推荐使用行话黑话、俚语、脏话等
38+
39+
● 不推荐使用网络流行语，比如“墙裂”、“童鞋”等流行语中故意的谐音错别字
40+
41+
## 用户导向
42+
43+
技术文档中应该以用户为导向。为编写出可用性较高的文档，文档工程师必须尽量站在用户的角度思考问题。具体要求有：
44+
45+
● 文档工程师应充分考虑文档受众的技术水平分布以及实际技术操作中可能出现的问题，尽可能全面、清晰地将技术信息普及给大众。
46+
47+
● 对于操作型技术文档，除语言审校外，建议再进行一次“文档可用性测试”——一位无技术背景的测试人员参照该文档进行完整操作，如操作顺利成功，代表该文档可用性测试通过；如失败，则需要继续修改完善文档。
48+
49+
## 用词恰当
50+
51+
用词恰当体现在两个方面：用词正确及用词统一。本节从禁用词和常用语两方面介绍了相应规范。
52+
53+
### 禁用词
54+
55+
用词正确体现在不使用有冒犯性的禁用词。技术文档中的禁用词可参考[新华社 2015 年 11 月发布的《新华社新闻报道中的禁用词（第一批）》](https://www.digitaling.com/articles/22975.html)。技术文档虽不是新闻报道，但作为技术传播领域的大众传播物，应当同样考虑文档传播带来的影响。避免使用具有冒犯性的词语，能为个人或组织节省不必要的麻烦。
56+
57+
以下是《新华社新闻报道中的禁用词（第一批）》中比较适用于技术文档的几点：
58+
59+
● 对有身体伤疾的人士不使用“残废人”、“独眼龙”、“瞎子”、“聋子”、“傻子”、“呆子”、“弱智”等蔑称，而应使用“残疾人”、“盲人”、“聋人”、“智力障碍者”等词语。
60+
61+
● 报道各种事实特别是产品、商品时不使用“最佳”、“最好”、“最著名”等具有强烈评价色彩的词语。
62+
63+
● 医药报道中不得含有“疗效最佳”、“根治”、“安全预防”、“安全无副作用”等词语，药品报道中不得含有“药到病除”、“无效退款”、“保险公司保险”、“最新技术”、“最高技术”、“最先进制法”、“药之王”、“国家级新药”等词语。
64+
65+
● 作为国家通讯社，新华社通稿中不应使用“哇噻”、“妈的”等俚语、脏话、黑话等。如果在引语中不能不使用这类词语，均应用括号加注，表明其内涵。近年来网络用语中对脏语进行缩略后新造的“SB”、“TMD”、“NB”等，也不得在报道中使用。
66+
67+
### 2.6.2 常用词
68+
69+
常用词指在编写一篇或一系列技术文档时，经常被使用的词语，如人称代词、指示代词、行文语态助词、操作动词、技术术语等。
70+
71+
技术文档中必须正确使用各种常用词。具体要求有：
72+
73+
1. 必须用对“的”、“地”、“得”，不能乱用。
74+
75+
● 【正确示例一】她露出了开心的笑容。（形容词＋的＋名词）
76+
77+
● 【正确示例二】她开心地笑了。（副词＋地＋动词）
78+
79+
● 【正确示例三】她笑得很开心。（动词＋得＋副词）
80+
81+
2. 必须明确“其”、“该”、“此”、“这”等代词指代的内容，保证不造成歧义。
82+
83+
● 【错误示例】从管理系统可以监视中继系统和受其直接控制的分配系统。
84+
85+
● 【正确示例】从管理系统可以监视两个系统：中继系统和受中继系统直接控制的分配系统。
86+
87+
3. 不建议使用表示程度、强调语气的词。例如，以下类型的词应避免使用。
88+
89+
● 表示程度的词：较多、较好、完全地、基本地、决定性的、最后的、仅仅、事实上、值得注意的
90+
91+
● 表示转折的词：当然、然而
92+
93+
● 表示量的词：有些、非常、大量、一些、少许、部分
94+
95+
4. 不建议使用引起歧义或含义模糊的动词。
96+
97+
● 【示例】“用信号线连接两个机柜”，如果表示两个机柜通过信号线进行通信，则“连接”这个词表示“通信”的概念模糊不明确，不利于翻译。
98+
99+
5. 不建议使用冷僻、生造或者文言文的词语，应该使用现代汉语的常用表达方式。
100+
101+
● 【错误示例】这是唯二的快速启动的方法。
102+
103+
● 【正确示例】这是仅有的两种快速启动的方法。
104+
105+
6. 禁止使用过多的形容词修饰名词。
106+
107+
● 【错误示例】此设备的使用必须在接受过本公司举办的正式的设备培训的技师的指导下进行。
108+
109+
● 【正确示例】此设备必须在技师的指导下使用，且指导技师必须接受过由本公司举办的正式设备培训。
110+
111+
另外，同一篇或同一系列技术文档中应尽可能统一用词，以降低阅读理解的难度。具体要求有：
112+
113+
1. 必须保证全文人称代词一致，人称不能反复改变。
114+
115+
● 推荐使用“您”或“你”来指称文档读者或用户，两者皆可，禁止混用
116+
117+
● 推荐使用“作者”、“文档作者”等第三人称形式来代指文档作者，不推荐使用“我”来代指文档作者，这样容易显得主观，也会在读者心中引起不必要的疑惑
118+
119+
● 可以使用“我们”来代称整个公司，但建议少用
120+
121+
2. 建议尽量使用主动语态，不使用被动语态。
122+
123+
● 【错误示例】假如此软件尚未被安装，
124+
125+
● 【正确示例】假如尚未安装这个软件，
126+
127+
【注意】汉语中使用被字句跟英语中使用被动式是不同的。在英语中，使用被动式的目的是为了避免提及施事者，但在汉语中的被字句往往带有被动的负面含义。另外，在中文文档中使用主动语态能帮助明确句子主语和宾语，这对后续的技术翻译工作极为重要。

‎build/html/_sources/关于本指南.md.txt

+32
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
# 关于本指南
2+
3+
本指南为中文技术文档的编写提供了一套风格指南规范。作者综合了在互联网上能找到的各家中文文案风格指南，尝试在中文技术文档的**语言风格、结构样式、内容元素、标点符号、格式排版**等方面给出建议。
4+
5+
## 适用范围
6+
7+
- 编写中文技术文档的文档工程师
8+
- 需要参与编写技术文档的产品研发人员
9+
- 审校文档过程中争议问题的裁决
10+
- 也可供软件界面、帮助文档等资料开发人员参考
11+
12+
## 使用原则
13+
14+
- 本指南只提供参考规范，不提供权威标准。事实上，本指南提出的一些规范在业界并无定论，有争议的点作者会以建议形式给出。
15+
- 本指南不是为了提供绝对正确的风格指南标准，而是在为日后业界建立标准铺路。
16+
- 本指南目前还只是建议版本，供所有从业者参与讨论。
17+
- 本指南将保持更新，欢迎任何人提出改进意见，如发现有错误或遗漏的点，请联系作者。
18+
19+
## 用词说明
20+
21+
本指南使用的表示“要求”的全部关键词已在下表第二列列出，具体释义请参见 [RFC2119](https://tools.ietf.org/html/rfc2119) 对相应词语做出的相关规定：
22+
23+
| RFC2119 中定义的关键词 | 对应的中文关键词 | 释义说明 |
24+
| -------------------------- | --------------------------- | ------------------------------------------------------------ |
25+
| MUST/REQUIRED/SHALL | 强制/必须/务必/只能 | 强制性规则，表示绝对要求这样做 |
26+
| MUST NOT/SHALL NOT | 禁止/不能/不要 | 强制性规则，表示绝对禁止这样做 |
27+
| SHOULD/RECOMMENDED | 应/应当/应该/建议/推荐 | 非强制性规则，表示一般情况下应该这样做，但在知悉全部后果的前提下，可以选择不这样做 |
28+
| SHOULD NOT/NOT RECOMMENDED | 不应当/不应该/不建议/不推荐 | 非强制性规则，表示一般情况下不应该这样做，但在知悉全部后果的前提下，可以选择这样做 |
29+
| MAY/OPTIONAL | 可以/可选 | 非强制性规则，表示这个要求是可选的，可以这样做，也可以不这样做 |
30+
31+
注：RFC (Request For Comments) 指关于互联网标准的正式文件，在这些文件的表述过程中，必须严格区分哪些是"建议" (suggestion)，哪些是"要求" (requirement)。所以，RFC2119 专门对五个关键词的涵义作出了规定，分别表示"要求"的严格程度。
32+

‎build/html/_sources/关于本指南/关于本指南.md.txt

+32
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
# 关于本指南
2+
3+
本指南为中文技术文档的编写提供了一套风格指南规范。作者综合了在互联网上能找到的各家中文文案风格指南，尝试在中文技术文档的**语言风格、结构样式、内容元素、标点符号、格式排版**等方面给出建议。
4+
5+
## 适用范围
6+
7+
- 编写中文技术文档的文档工程师
8+
- 需要参与编写技术文档的产品研发人员
9+
- 审校文档过程中争议问题的裁决
10+
- 也可供软件界面、帮助文档等资料开发人员参考
11+
12+
## 使用原则
13+
14+
- 本指南只提供参考规范，不提供权威标准。事实上，本指南提出的一些规范在业界并无定论，有争议的点作者会以建议形式给出。
15+
- 本指南不是为了提供绝对正确的风格指南标准，而是在为日后业界建立标准铺路。
16+
- 本指南目前还只是建议版本，供所有从业者参与讨论。
17+
- 本指南将保持更新，欢迎任何人提出改进意见，如发现有错误或遗漏的点，请联系作者。
18+
19+
## 用词说明
20+
21+
本指南使用的表示“要求”的全部关键词已在下表第二列列出，具体释义请参见 [RFC2119](https://tools.ietf.org/html/rfc2119) 对相应词语做出的相关规定：
22+
23+
| RFC2119 中定义的关键词 | 对应的中文关键词 | 释义说明 |
24+
| -------------------------- | --------------------------- | ------------------------------------------------------------ |
25+
| MUST/REQUIRED/SHALL | 强制/必须/务必/只能 | 强制性规则，表示绝对要求这样做 |
26+
| MUST NOT/SHALL NOT | 禁止/不能/不要 | 强制性规则，表示绝对禁止这样做 |
27+
| SHOULD/RECOMMENDED | 应/应当/应该/建议/推荐 | 非强制性规则，表示一般情况下应该这样做，但在知悉全部后果的前提下，可以选择不这样做 |
28+
| SHOULD NOT/NOT RECOMMENDED | 不应当/不应该/不建议/不推荐 | 非强制性规则，表示一般情况下不应该这样做，但在知悉全部后果的前提下，可以选择这样做 |
29+
| MAY/OPTIONAL | 可以/可选 | 非强制性规则，表示这个要求是可选的，可以这样做，也可以不这样做 |
30+
31+
注：RFC (Request For Comments) 指关于互联网标准的正式文件，在这些文件的表述过程中，必须严格区分哪些是"建议" (suggestion)，哪些是"要求" (requirement)。所以，RFC2119 专门对五个关键词的涵义作出了规定，分别表示"要求"的严格程度。
32+

‎build/html/_sources/关于本指南/目的.md.txt

+5
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
## 目的
2+
3+
- 提高中文文案的可读性
4+
- 避免文档工程师们对同一问题反复作出决策，降低团队成员之间的沟通成本
5+
- 帮助一个公司的文档团队统一文档风格，保证公司对外输出形象一致

‎build/html/_sources/目的.md.txt

+5
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
## 目的
2+
3+
- 提高中文文案的可读性
4+
- 避免文档工程师们对同一问题反复作出决策，降低团队成员之间的沟通成本
5+
- 帮助一个公司的文档团队统一文档风格，保证公司对外输出形象一致

0 commit comments

Comments
 (0)