Skip to content

Commit

Permalink
[ISSUE-3725][doc] Migrate the StreamPark website/doc specification pa…
Browse files Browse the repository at this point in the history 
…ge into website repo.
  • Loading branch information
@RocMarshal
RocMarshal committed May 26, 2024
1 parent 4045755 commit 04b1803
Showing 1 changed file with 390 additions and 0 deletions.
390 changes: 390 additions & 0 deletions community/submit_guide/documentation-style-guide.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,390 @@
---
id: 'documentation-style-guide'
title: 'Documentation Style Guide'
sidebar_position: 4
---

<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
https://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->


## 1 The English edition specification

### 1.1 Manual Line Break
When you're writing documents, please break lines intentionally around the approximate
character limit (120 chars), which makes it easier for review and developers to read.

### 1.2 Avoid Long and Complicated Sentences
- Reduce the number of long and complex sentences.
- Break them down into several simpler sentences.

### 1.3 Reduce Markers
Reduce the number of markers (such as code blocks, bold text) unless absolutely
necessary, as the rendered version becomes very difficult to read.

### 1.4 Correct Item Reference
- Positive：
> Apache HBase, ClickHouse.
- Negative：
> Apache Hbase, Clickhouse.
### 1.5 Integrity and Availability
- English documentation should have corresponding Chinese documentation pages.
- Internal links referenced in the English documentation should be functional,
and corresponding pages in other languages should be accessible.
- External links referenced in the English documentation should be functional.
- If there are incomplete resources, it's preferable to declare the supplementary
time or plan for missing resources, and add a simple explanation if necessary.

### 1.6 [3-C rules](https://developer.mozilla.org/zh-CN/docs/MDN/Writing_guidelines/Writing_style_guide#%E8%80%83%E8%99%91%E5%86%99%E4%BD%9C%E7%9A%84%E2%80%9C3c%E2%80%9D%E5%87%86%E5%88%99)
- Clarity:

Ensure that your writing is clear and simple. Generally speaking,
use active voice and unambiguous pronouns.
Write short sentences, insisting on one viewpoint per sentence.
Before using new terminology, it is necessary to define it and maintain the target audience.

- Simplicity:

Knowing how much to say is important when writing any document. If you provide too much detail,
the page will become dull and difficult to read, and it will be rarely used.

- Consistency:

Ensure that you consistently use the same wording throughout the entire page and across
multiple pages.

### 1.7 Using inclusive expression

Click [here](https://developer.mozilla.org/zh-CN/docs/MDN/Writing_guidelines/Writing_style_guide#%E4%BD%BF%E7%94%A8%E5%8C%85%E5%AE%B9%E6%80%A7%E8%AF%AD%E8%A8%80)
for more details.

### 1.8 Space
- Between English words and numbers
- Between English words and units
- Between English words and links
### 1.9 Punctuation Marks
- Use half-width English punctuation marks when using the English input method.
### 1.10 Capitalization of The First Letter
The first letter of the first word in a sentence should be capitalized unless there are special circumstances.
- Positive：
> 'nameMap'(Assuming the attribute name is 'nameMap') is an attribute of class `Demo`.
>
> Jige is a pretty basketball player.
- Negative：
> 'NameMap' is an attribute of class `Demo`.
>
> jige is a pretty basketball player.
### For better

If you are interested in ensuring the standardized writing quality of the document,
please let's reference this
[link](https://developer.mozilla.org/zh-CN/docs/MDN/Writing_guidelines/Writing_style_guide)
to do better.


## 2 The Chinese edition specification
### 2.1 Space
#### 2.1.1 Between Chinese and English

Positive:

> Apache Flink 是 Apache StreamPark 支持的计算引擎之一。
Negative:

> Apache Flink 是 Apache StreamPark支持的计算引擎之一。
>
> Apache Flink是 Apache StreamPark 支持的计算引擎之一。
Specifically: For product terms, write them in the officially defined format.

#### 2.1.2 Between Chinese and the digital

Positive:

> 某个公司的 Apache StreamPark 平台运行了 5000 个 Apache Flink 作业。
Negative:

> 某个公司的 Apache StreamPark 平台运行了5000 个 Apache Flink 作业。
>
> 某个公司的 Apache StreamPark 平台运行了 5000个 Apache Flink 作业。
#### 2.1.3 Between the unit and the digital

Positive:

> 某公司的 Apache StreamPark 平台可用内存资源接近 100 PB。
Negative:

> 某公司的 Apache StreamPark 平台可用内存资源接近 100PB。
Specifically, there is no need to add spaces between degrees, percentages, and numbers:

Positive:

> 角度为 90° 的角，就是直角。
>
> Apache StreamPark 可以给 Apache Flink 作业管理带来约 15% 的效率提升。
Negative:

> 角度为 90 ° 的角，就是直角。
>
> Apache StreamPark 可以给 Apache Flink 作业管理带来约 15 % 的效率提升。
#### 2.1.4 No spaces between full width punctuation and other characters

Positive:

> 公司的计算平台刚刚升级成了 Apache StreamPark，好开心！
Negative:

> 公司的计算平台刚刚升级成了 Apache StreamPark ，好开心！
>
> 公司的计算平台刚刚升级成了 Apache StreamPark， 好开心！
#### 2.1.5 Spaces between links

Usage:

> 请 [提交一个 issue](http://localhost) 反馈到 Apache StreamPark 社区。
>
> 访问 Apache StreamPark 的最新动态，请 [点击这里](http://localhost) 进行订阅！
Compared usage pairs:

> 请[提交一个 issue](http://localhost)反馈到 Apache StreamPark 社区。
>
> 访问 Apache StreamPark 的最新动态，请[点击这里](http://localhost)进行订阅！

### 2.2 Punctuation marks

#### 2.2.1 Do not repeat punctuation marks


Positive:

> 哇！Apache StreamPark！
Negative:

> 哇！Apache StreamPark！！！

[Full angle and half angle](https://zh.wikipedia.org/wiki/%E5%85%A8%E5%BD%A2%E5%92%8C%E5%8D%8A%E5%BD%A2)

#### 2.2.2 Use full width Chinese punctuation

Positive:

> Apache StreamPark 是一个不错的大数据计算平台的选型。
Negative:

> Apache StreamPark 是一个不错的大数据计算平台的选型.
Specifically, when Chinese sentences contain English book or newspaper titles,
Chinese book titles should not be borrowed, but should be indicated in italics.

#### 2.2.3 Use half width character numbers

Positive:

> 某公司的 Apache StreamPark 平台稳定运行了 1000 个 Application。
Negative:

> 某公司的 Apache StreamPark 平台稳定运行了 １０００ 个 Application。

#### 2.2.4 Special usage of half corner punctuation

Specifically: When encountering complete English sentences and special nouns,
use half width punctuation in their content.

Positive:

> 乔布斯那句话是怎么说的？“Stay hungry, stay foolish.”
>
> 推荐你阅读 *Hackers & Painters: Big Ideas from the Computer Age*，非常地有趣。
Negative:

> 乔布斯那句话是怎么说的？“Stay hungry，stay foolish。”
>
> 推荐你阅读《Hackers＆Painters：Big Ideas from the Computer Age》，非常的有趣。
### 2.2.5 Quotation marks

The following methods are recommended:

> 鸡哥说：“老师，‘鸡你太美’的‘坤’是谁？”

### 2.3 The noun

#### 2.3.1 Correct capitalization

Proper nouns should be capitalized correctly.

Positive:

> 使用 GitHub 克隆 Apache StreamPark 代码仓库。
>
> Apache StreamPark 支持的生态有 Apache Flink、Spark、Flink-CDC、Paimon、Hudi, Inc.。
Negative:

> 使用 gitHub 克隆 Apache StreamPark 代码仓库。
>
> 使用 Github 克隆 Apache StreamPark 代码仓库。
>
> Apache StreamPark 支持的生态有 Apache flink、Spark、Flink-CDC、Paimon、Hudi, Inc.。
>
> Apache StreamPark 支持的生态有 apache Flink、spark、flink-cdc、Paimon、Hudi, Inc.。

#### 2.3.2 Inappropriate abbreviations

Do not use unconventional abbreviations.

Positive:

> Apache StreamPark 使用了 TypeScript、HTML5 技术吗？
Negative:

> Apache StreamPark 使用了 ts、h5 技术吗？

## 3 中文翻译
- 社区推荐优先推荐撰写英文文档，然后根据英文文档翻译为中文文档。
- 翻译时以 `2 中文规范` 为基准，并兼顾如下几点：

### 3.1 使用纯文本工具进行翻译，不要使用富文本工具
使用纯文本工具可以进行翻译，可以有效避免增加新行、删除行、破坏链接、破坏引号、破坏星号等行为。

### 3.2 汉字与英文、数字之间需空格
参考中文文档规范部分

### 3.3 文档链接

英文版文档中可能会包含引用文档中其他文章的绝对链接，此时要注意将链接修改为中文版的 URL。


### 3.4 一般用“你”，而不是“您”

为了风格统一，我们建议在一般情况下使用“你”即可，这样与读者距离近一些。当然必要的时候可以使用“您”来称呼，比如 warning 提示的时候。

### 3.5 示例代码及注释

示例代码中的注释最好能够翻译，当然也可以选择不翻译（当注释很简单时）。

### 3.6 意译优于直译

社区不推荐把原文一字不漏地、逐句地翻译。因为有些情况下不但不准确而且有时候读着会很别扭。所以建议在翻译完以后，
自己多读几遍，看看是否符合原意、是否绕口、是否简洁。
在充分理解原文的基础上，可以适当采用意译的方式来翻译。有时候为了简化句子，有些数量词、助词、主语都可以省略。

简述两种示例情况如下：

#### 3.6.1 不必要的所有格翻译
英文中经常会用 `'s` 来表达从属关系，一字不落地都将其翻译成 "的" 就会很翻译腔。在中文里面有些 "的" 完全可以去掉，
不会影响表达的意思，还能简洁很多，看下面的例子：
- 示例：
Flink's documentation is located in the docs folder in Flink's source code repository

- Negative: 将"的"字都翻译出来，但是读起来很不顺畅
>Flink 的文档位于 Flink 的源码仓库的 docs 文件夹中。
- Positive: 去掉不必要的"的"字，就会简洁很多：
>Flink 文档位于 Flink 源码仓库的 docs 文件夹中。

#### 3.6.2 不必要的量词/冠词的翻译

英文一般比较严谨，当代表多个时，会使用复数名字，在翻译成中文时，一般不需要刻意把这种复数翻译出来。

在英文里，当单数可数名词时，前面一般会有“a”或“an”，但在中文里我们大多数时候是不用把“一个...”给翻译出来的。

- 示例：
State is a first-class citizen in Flink.

- Negative: 将“a”翻译成“一个”
>状态是 Flink 中的一个一等公民
- Positive: 去掉不必要的“一个”
>状态是 Flink 中的一等公民
虽然看起来没什么问题，但是这里的“一个”完全是多余的，去掉之后不但不会影响翻译效果，而且还会显得更加简洁。


### 3.7 专业术语
- Application，Checkpoint，Savepoint，Team 等，及当前没有合适的对应统一名词的翻译可以直接使用英文进行表述
- 重要：文章中第一次出现专业术语翻译的地方需要给出英文原文。例如：“如果看到反压（back pressure）警告，则...”
- 专有词要注意大小写，如 Apache Flink，Java，Scala，API，SQL，不要用小写的 apache flink, java, scala, api, sql。
- 当单词是指代码中的属性名、方法名、对象名、类名、标签名等时，可以不译。
例如 "parallelism parameter" 不需要翻译成“并发参数”，而是应为“parallelism 属性”。

### 3.8 编写或者翻译文档时及时换行
编写文档时，在近似行字符数（120 chars）附近主动换行，方便 review 和 开发者阅读.


## 4 ASF Compliance

- Products like Hadoop, Spark, Flink under Apache require the prefix "Apache" when used (in documentation, images).
- Replace "streamx" / "StreamX" images with corresponding images from Apache StreamPark.
- Images with watermarks involve brand issues and require brand declaration.
- Temporarily take down video resources. Adjust or remove references to video resources in the documentation.
- Replace casual abbreviations like "K8s" with "Kubernetes" or "kubernetes", adopting the approach of retaining the original name.


## 5 How to contribute

1. Feel free to select a page that you want to improve
2. Create an [issue](https://github.com/apache/incubator-streampark/issues/new) whose name starts
with prefix '[Improve][website] Improve {page-name}'.
It would be better to associate with the [\#3724 (Umbrella ISSUE ID)](https://github.com/apache/incubator-streampark/issues/3724)
3. Do the corresponding check and adjustment work based on the specification mentioned above like follows:
- https://github.com/apache/incubator-streampark-website/pull/361
- https://github.com/apache/incubator-streampark-website/pull/363
4. Do commit message pattern like '[ISSUE-XXX][website] Improve {page-name}'
5. Drive the PR, fill the `ISSUE(you created) ID` in the PR page.


## References

- https://github.com/sparanoid/chinese-copywriting-guidelines/blob/master/README.zh-Hans.md
- https://github.com/apache/incubator-streampark-website/pull/347
- https://github.com/apache/incubator-streampark-website/pull/349
- https://cwiki.apache.org/confluence/display/FLINK/Flink+Translation+Specifications
- https://lists.apache.org/thread/0p40kdbkoqdto2zlvwbw3r9xo3hfnm4g
- [Guidelines for Using Capital Letters - ThoughtCo.](https://www.thoughtco.com/guidelines-for-using-capital-letters-1691724)
- [Letter case - Wikipedia](https://en.wikipedia.org/wiki/Letter_case)
- [Punctuation - Oxford Dictionaries](https://en.oxforddictionaries.com/grammar/punctuation)
- [Punctuation - The Purdue OWL](https://owl.english.purdue.edu/owl/section/1/6/)
- [How to Use English Punctuation Correctly - wikiHow](https://www.wikihow.com/Use-English-Punctuation-Correctly)
- [Format - openSUSE](https://zh.opensuse.org/index.php?title=Help:%E6%A0%BC%E5%BC%8F)
- [Full Form and Half Form - Wikipedia](https://zh.wikipedia.org/wiki/%E5%85%A8%E5%BD%A2%E5%92%8C%E5%8D%8A%E5%BD%A2)
- [Document Writing Specification](https://developer.mozilla.org/zh-CN/docs/MDN/Writing_guidelines/Writing_style_guide)


0 comments on commit 04b1803

Please sign in to comment.