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
