GitHub user RocMarshal edited a discussion: [Proposal] Improve the
documentation of Apache StreamPark website
# Apache StreamPark documentation style guide
# 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 Space
- Between English words and numbers
- Between English words and units
- Between English words and links
## 1.7 Punctuation Marks
- Use half-width English punctuation marks when using the English input
method.
## 1.8 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.
# 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]() 反馈到 Apache StreamPark 社区。
>
> 访问 Apache StreamPark 的最新动态，请 [点击这里]() 进行订阅！
Compared usage pairs:
> 请[提交一个 issue]()反馈到 Apache StreamPark 社区。
>
> 访问 Apache StreamPark 的最新动态，请[点击这里]()进行订阅！
## 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)
# Final
This is a draft doc. We'll re-type it in the correct style based on the final
specification items.
Any suggestion is appreciated!
GitHub link: https://github.com/apache/incubator-streampark/discussions/3715
----
This is an automatically sent email for dev@streampark.apache.org.
To unsubscribe, please send an email to: dev-unsubscr...@streampark.apache.org
