diff --git a/community/submit_guide/documentation-style-guide.md b/community/submit_guide/documentation-style-guide.md new file mode 100644 index 0000000000..5c3495b5ce --- /dev/null +++ b/community/submit_guide/documentation-style-guide.md @@ -0,0 +1,390 @@ +--- +id: 'documentation-style-guide' +title: 'Documentation Style Guide' +sidebar_position: 4 +--- + + + + +## 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 平台稳定运行了 1000 个 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) + +