本指南规范极狐GitLab 的中文文档写作风格，包括语言风格、文档结构、标点符号和其他规范等。 为文档人员、技术人员及市场人员等在撰写极狐GitLab 技术文档、用户手册及宣传文稿时提供规范及建议，进而提升文档内容的准确性、规范性、一致性和可读性，并为争议提供指导。
我们力求准确、简洁和规范。我们的目标是提供易于阅读和理解的信息。
在编写文档之前，最重要的一步就是明确文档的面向对象，从而根据不同对象的知识水平和阅读需求调整文档的内容侧重及语言风格，展现不同的广度、深度、专业性及趣味性。 例如，面向用户的文档不应过多地使用深奥的原理和专业术语，应尽量以普通用户可以理解的语言编写。在需要提及专业术语时，建议在文档合适的位置添加术语解释，防止用户理解偏差影响阅读效果。 避免使用小范围内熟知但未在业界广泛使用的行话和缩写。如果必须使用，则需要添加注释加以说明。
明确对象之后，编者需要以文档对象为出发点，文档内容紧密贴合对象需求。 例如，在操作类文档中，编者需要详细写出用户在实际操作中的每一个步骤，每一个字段如何填写、取值范围为多少、限制条件是什么，和出现某种类型的错误需要如何处理等。 在产品宣传类文档中，编者应该侧重表述产品功能特点、为客户提供的价值和超越竞品的优势等。
无论是哪种类型的文档，正确性和准确性都是第一要义。编者需要确保文档中出现的原理、定义、词汇、语法、拼写及标点等正确无误，不会让用户因文档的用词错误或模糊造成理解错误及偏差。 例如，在操作手册中描述 "一段时间后，页面会显示操作成功的提示"。不同的人对于 "一段时间" 有不同的定义，一段时间究竟是几秒钟还是几分钟？这个标准不应该由用户来猜测或定义， 编者有义务在文档中为其设定一个具体的数值作为参考标准。
对于一些技术文档，编者在准确描述技术原理、产品功能或操作步骤的同时，还需要保证文档简洁明确、条理清楚且逻辑清晰。 尽量做到一个段落只描述一个主题，一个句子只侧重一个关键词，一个步骤只写一个操作。这样用户在浏览文档的时候，就可以快速定位到相应的位置并获取需要的信息。
我们通常向目标读者传达的应该是不经过任何主观处理的客观事实，除非是一些具有宣传或引导属性的文档。作为编者，我们在文档中阐述的内容不应违背客观事实，不应带有主观色彩，不应不合时宜地使用修辞手法。
我们面对的是不同知识水平和理解能力的读者，因此编者应该将自己定位为客观的叙述者，只提供真实客观的信息，对于客观信息的消化理解和引申迁移都需要由读者来完成。
这虽然不是文档写作的必要因素，但却是衡量文档质量高低的关键因素。同样描述一件事情，有些文档会高效为我们提供帮助，有些看完却依然一头雾水。
文档需要在保证准确严谨的同时尽量保持语言的简洁直接，不要采用冗长的句子或在文档的不同位置反复陈述一个观点。 此外，编者还可以采用文字之外的其他形式来达到易于理解的目的。例如 "文不如表，表不如图"，一张流程图的效果比一大段文字更直观，一个对比表格会让用户更清晰地感受差异，一张类比图会比让读者自行想象更节省时间。
每个行业都有行业规范和广被认可的约定，文档写作需要遵守这些规范和约定，不能自成一派，各行其是。例如，敏捷（Agile）是一种软件开发的方法论，但是有编者认为相比 "敏捷"，"灵活" 会赋予 "Agile" 更形象的含义，所以在文档中使用 "灵活" 代替 "敏捷"。这是一种错误的做法，会给读者带来概念混淆和理解偏差。
一个文档中所使用的术语、名称和说法需要保持统一，确保高度的一致性。例如，在一个文档中，您将一个群组的人称为 "用户"，那么在整个文档中都需要以 "用户" 进行称呼，而不是混杂 "用户"、"客户" 或 "消费者" 等。 此外，保持样式的统一同样重要。除非另有规定或目的，编者需要保持各类样式的统一，包括全文字体的统一，为项目符号选择相同的样式或统一表头图注的样式等。
考虑到文档编写会采用不同的语言工具，所以文档结构章节主要介绍标题、正文、项目列表、步骤、表格和图片在内容方面的规范。对于格式方面的要求，请以各语言规范为准，例如编写规范和 GLFM。
标题对于读者快速了解章节内容和全文结构具有很重要的作用，标题是下面段落所描述主题的精练表达。标题一般分为多个层级，并在逻辑上具有包含关系。
标题需要遵循以下原则：
正文由段落组成，段落由句子组成，句子是根据语法结构由词和词组串联起来的可以表达完整意思的语言单元。
正文需要遵循以下原则：
项目列表可以将大段文本转化为无序列表，使文档条理清晰、简洁直观。
项目列表需要遵循以下原则：
极狐GitLab 会帮助您：
● 快速识别并定位阻塞、及时扫清障碍并提高生产效率。
● 借助多种衡量指标和研发价值流洞察等功能，专注于交付价值
● 降低软件开发全生命周期中的风险和成本。
● 在不影响速度或支出的情况下实现自动化安全与合规。
● 更快地交付更好的软件，助力数字化转型
极狐GitLab 会帮助您：
● 快速识别并定位阻塞、及时扫清障碍并提高生产效率。
● 借助多种衡量指标和研发价值流洞察等功能，专注于交付价值。
● 降低软件开发全生命周期中的风险和成本。
● 在不影响速度或支出的情况下实现自动化安全与合规。
◾ 代码质量检查
◾ 代码合规检查
◾ 代码自动测试
● 更快地交付更好的软件，助力数字化转型。
极狐GitLab 会帮助您：
● 快速识别并定位阻塞、及时扫清障碍并提高生产效率。
● 借助多种衡量指标和研发价值流洞察等功能，专注于交付价值。
● 风险和成本控制。
● 自动化安全与合规。
● 更快地交付更好的软件，助力数字化转型。
极狐GitLab 会帮助您：
● 快速识别并定位阻塞、及时扫清障碍并提高生产效率。
● 借助多种衡量指标和研发价值流洞察等功能，专注于交付价值。
● 风险和成本控制。
● 自动化安全与合规。
● 更快地交付更好的软件，助力数字化转型。
极狐GitLab 会帮助您：
● 快速识别并定位阻塞、及时扫清障碍并提高生产效率。
可以迅速地定位阻塞位置，通知相关人员进行故障解决。
● 借助多种衡量指标和研发价值流洞察等功能，专注于交付价值。
● 进行风险和成本控制。
帮助您的组织控制风险和成本。
● 进行自动化安全与合规。
● 更快地交付更好的软件，助力数字化转型。
步骤需要遵循以下原则：
创建议题：
1. 在您想创建议题的项目或群组中，点击 **议题** > **列表**。
2. 点击右上角的 **新建议题**。
3. 填写标题、类型、描述、指派人、里程碑和标记。
4. 点击 **创建议题**。
创建议题：
1. 在您想创建议题的项目或群组中，点击 **议题** > **列表**。点击右上角的 **新建议题** 并填写标题、类型、描述、指派人、里程碑和标记等。
2. 点击 **创建议题**。
创建议题：
1. 在您想创建议题的项目或群组中，点击 **议题** > **列表**。
2. 点击右上角的 **新建议题**。
3. 填写标题、类型、描述、指派人、里程碑和标记等。
4. 点击 **创建议题**。
注：在步骤三中，标题是指您为新创建的议题所添加的标题；类型分为议题和事件；描述是指您对该议题要解决的问题、计划的工作或改进的建议等的详细描述。
如果您想直观地展示产品或系统的各项功能或者对比两个产品的差异时，表格是很好的表现方式。
表格需要遵循以下原则：
| 产品特点 | 详细解释 | 是否适用 |
|---|---|---|
| 高可用 | 可靠性高 | 是 |
| 可扩展 | 扩展性好 | 是 |
| 易运维 | 无 | 否 |
| 内存大 | 内存充足 | 否 |
图片需要遵循以下原则：
文档中会使用到的标点符号包括逗号、句号、顿号、冒号、分号、括号、书名号、破折号、斜杠、反斜杠和引号等。如果标点符号使用错误，可能会造成歧义。 我们需要在文档中正确使用各类标点符号，像对待文字一样严谨对待标点符号。
逗号表示句子的一般性停顿，是使用最广泛的标点符号。 文档切忌一逗到底。因为在一个段落中，一般有一个主观点，若干个分观点。主观点需要以句号结束，每个分观点需要以分号或句号结束。 一逗到底会导致文档层次混乱，结构不清，导致阅读不友好。
句号一般表示一个陈述句的完结。使用句号需要注意以下几点：
极狐GitLab 是一个一站式交付的开放一体式 DevOps（意为 Development+Operations）平台。
极狐GitLab 是一个一站式交付的开放一体式 DevOps 平台。（一站式是指一个平台或系统满足用户的所有需求。）
顿号表示并列的词、词组或短句之间的停顿。
使用顿号需要遵循以下原则：
极狐GitLab 具有一体化、更高效、更安全和更开放的特点。
该产品具有安装简单，操作、使用方便，易于维护的特点。
该产品具有界面友好、安装简单、操作方便和易于维护的特点。
该产品具有界面友好、安装简单、操作方便，和易于维护的特点。
在大多数技术文档中，问号和感叹号使用频率较低。问号一般使用在常见问题模块中，而感叹号一般使用在警告中，提示用户某个操作会带来严重后果。例如：在安装过程中遇到报错怎么办？警告：严禁在未保存的情况下强制关闭计算机，否则您的内容将全部消失！
6 < 9
8 > 7
a ≥ b
69%
27°C
$68
Ctrl+V
Shift+Alt
Tab+A
强大的处理能力
电脑的屏幕
快速地点击
天渐渐地暗了
跑得真快
红得发紫
在文档中提及系统中的界面词时，必须与界面中的文字保持一致且界面文字一般加粗。界面词包括按钮文字、菜单文字、报错信息和提示信息等。
如果界面中显示为 "新建议题"，而您在步骤中描述为 "点击右上角的创建议题"，就是一种错误写法。
21：36：09
3.1 CI/CD 在软件开发中的广泛应用
CI（Continuous Integration）和 CD（Continuous Deployment）是使用持续的方法交付软件的一种方法。
国内 建议改为：中国国内
海外 建议改为：中国之外的国家和地区