---

layout: dev-cn title: Kylin 文档撰写规范 categories: development permalink: /cn/development/doc_spec.html

本文从章节结构、元素标记、用语规范、文件/路径规范等方面对 Kylin 文档的撰写规范进行了详述。

准备工作

1. 请您根据 如何写文档 准备撰写文档有关的环境，了解 Kylin 文档结构。
2. Kylin 文档使用 Markdown 语法书写，以下简称 md。请您确保您熟悉 Markdown 语法。

章节结构

• 每个章节的内容以多个小节的形式组织，每个小节的标题使用 Heading 3 样式。如： ### 安装 Kylin
• 如果需要在小节内进一步对内容进行组织，请使用 无序 / 有序 列表，尽量不使用 Heading 4，完全避免 Heading 5。如： ### 安装 Kylin
  1. 首先，…… * 运行…… * 解压……

元素标记

• 粗体 使用粗体标记您需要强调的内容。如：

  1. 强调 GUI 上某个组件的名称。
  2. 强调一个新概念。
  3. 强调用户在阅读时容易忽略的否定词。

• 斜体

  1. 中文文档中一般不使用斜体。
  2. 英文文档中对于以下情形可以使用斜体，如数据库表名、列名等。

• 引用

  1. 使用引用来标记 次要信息 / 补充信息，即不影响正常理解和使用的扩展信息。如： > 您可以继续阅读以获得更多关于……的信息。
  2. 使用引用来标记 提示信息。
  • 对于一般性提示信息，使用 提示 / Note 开头。
  • 对于关键或警示的提示信息，使用 注意 / Caution 开头。

• 行内代码 使用行内代码标记一切可能会被用户输入到 shell / config 中的内容，比如文件路径、 Unix 账户、配置项和值等。

• 代码段 使用代码段标记所有用户需要执行的 shell 命令和 config 配置，统一格式且需要足够凸显。如：

  1. shell 命令 ```sh $KYLIN_HOME/bin/kylin.sh start ```

  2. config 配置 ```properties kylin.env.hdfs-working-dir=/kylin ``` ``` xml <property> <name>mapreduce.map.memory.mb</name> <value>2048</value> </property> ```

用语规范

• 英文专用词汇

  • 中文文档中，一般出现的英文词汇都需要使用首字母大写。如： Cube 概念是指一个 Cuboid 的集合，其中……。
  • 英文文档中，当第一次出现某个英语专有词汇时，需要将首字母大写，并且用粗体强调，其他时候不需要大写 ”cube“ 或者 ”model“ 等词语。

• 中英文（数字）混合 在中文版中，所有出现的英文（数字）需要在两端中英文交界处添加一个额外英文半角空格，以增强中英文混排的美观性和可读性。

• 标点符号

  • 在中文文档中，请一律使用中文标点符号。

• UI 交互的描写

  1. 统一对页面元素的称呼。 顶部状态栏 / the top header 左侧导航栏 / the left navigation xxx 页面 / the xxx page xxx 面板 / the xxx panel xxx 对话框 / the xxx dialog
  2. 用加粗样式强调交互元素。如： 点击**提交**按钮。
  3. 用 -> 说明连续操作。