This is an automated email from the ASF dual-hosted git repository. xxyu pushed a commit to branch document in repository https://gitbox.apache.org/repos/asf/kylin.git
commit 724160c4263c59cb8b0fae98e088a981195af0fe Author: xuekaiqi <kaiqi....@qq.com> AuthorDate: Wed Aug 19 13:44:52 2020 +0800 KYLIN-4708 add doc-spec in english version and fix dead link --- website/_data/development.yml | 1 + website/_dev/doc_spec.cn.md | 2 +- website/_dev/doc_spec.md | 96 +++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 98 insertions(+), 1 deletion(-) diff --git a/website/_data/development.yml b/website/_data/development.yml index a3d1d03..68f3cbc 100644 --- a/website/_data/development.yml +++ b/website/_data/development.yml @@ -25,6 +25,7 @@ - howto_contribute - howto_become_apache_committer - howto_docs + - doc_spec - howto_package - howto_hbase_branches - howto_release diff --git a/website/_dev/doc_spec.cn.md b/website/_dev/doc_spec.cn.md index 1089cd3..f340043 100644 --- a/website/_dev/doc_spec.cn.md +++ b/website/_dev/doc_spec.cn.md @@ -10,7 +10,7 @@ permalink: /cn/development/doc_spec.html ### 准备工作 -1. 请您根据 [如何写文档](howto_docs.cn.md) 准备撰写文档有关的环境,了解 Kylin 文档结构。 +1. 请您根据 [如何写文档](/cn/development/howto_docs.html) 准备撰写文档有关的环境,了解 Kylin 文档结构。 2. Kylin 文档使用 Markdown 语法书写,以下简称 md。请您确保您熟悉 [Markdown 语法](https://guides.github.com/features/mastering-markdown/)。 ### 章节结构 diff --git a/website/_dev/doc_spec.md b/website/_dev/doc_spec.md new file mode 100644 index 0000000..9a3e7a3 --- /dev/null +++ b/website/_dev/doc_spec.md @@ -0,0 +1,96 @@ +--- +layout: dev +title: Kylin Document Writing Specification +categories: development +permalink: /development/doc_spec.html +--- + +This article describes the Kylin document writing specifications. We will introduce the chapter structure, element tag, term specification, file/path specification, etc. + +### Preparation + +- Please prepare the environment related to writing documents according to [How to Write Document](/development/howto_docs.html) and understand the Kylin document structure. + +- Kylin documents are written in Markdown syntax, hereinafter referred to as md. Please make sure you are familiar with [Markdown Syntax](https://guides.github.com/features/mastering-markdown/). + +### Chapter Structure + +- The content of each chapter is organized in multiple subsections, and the heading of each subsection uses **Heading 3 style**. For example: + \#\#\# Install Kylin +- If you need to further organize the content within the subsections, please use **Unordered / Ordered List**, try not to use **Heading 4**, and avoid **Heading 5** completely. For example: + \### Install Kylin + 1. First, ... + \* Run... + \* Unzip... + +### Element Tag + +- Bold + Use bold to mark the content you need to emphasize. Such as: + + - Emphasize the name of a component on the GUI. + - Emphasize a new concept. + - Emphasize negative words that users tend to ignore when reading. + +- Italic + + - Italics are generally not used in Chinese documents. + + - Italics can be used in English documents for the following situations, such as database name, table name, column name, etc. + +- Quote + + - Use quote to mark secondary information / supplementary information, that is, extended information that does not affect normal understanding and use. Such as: + + \> You can continue reading to get more information about... + + - Use quote to mark reminders. + - For general prompt information, use **Note** at the beginning. + - For critical or warning messages, start with **Caution**. + +- Inline code + Use inline code to mark everything that **may** be **entered by the user into the shell / config**, such as file paths, Unix accounts, configuration items, and values. + +- Code snippet + Use code snippets to mark **shell commands and config configurations that all users need to execute**, in a unified format and need to be sufficiently prominent. Such as: + + - shell commands + + \`\`\`sh + $KYLIN_HOME/bin/kylin.sh start + \`\`\` + + - config configurations + + \`\`\`properties + kylin.env.hdfs-working-dir=/kylin + \`\`\` + \`\`\` xml + <property> + <name>mapreduce.map.memory.mb</name> + <value>2048</value> + </property> + \`\`\` + +### Term Specification + +- English vocabulary + - In Chinese documents, the first letter of the English words must be capitalized. For example: + Cube 概念是指一个 Cuboid 的集合,其中……。 + - In English documents, when an English-specific vocabulary appears for the first time, the first letter must be capitalized and emphasized in bold. Other times, words such as "cube" or "model" are not required to be capitalized. + +- Punctuation + - In Chinese documents, **Please always use Chinese punctuation**. + +- Description of UI interaction + - Unify the title of page elements. + - the top header + - the left navigation + - the xxx page + - the xxx panel + - the xxx dialog + +- Use **bold style** to emphasize interactive elements. For example: + Click the \*\*Submit\*\* button. + +- Use **->** to illustrate continuous operation. \ No newline at end of file