[Proposal] Improve the documentation style of Apache StreamPark website #3715
Replies: 5 comments
-
|
Thanks @RocMarshal for the great work! |
Beta Was this translation helpful? Give feedback.
-
|
I think you can also use my previous two PRs as flow demo |
Beta Was this translation helpful? Give feedback.
-
|
I think we need to think carefully about splitting tasks. If it were me, I would suggest one document and one issue, so that contributors can learn more. |
Beta Was this translation helpful? Give feedback.
-
|
It's a great job. We can continue to improve the document specifications and put them in the official website document as a guide. |
Beta Was this translation helpful? Give feedback.
-
|
We can refer to this document: |
Beta Was this translation helpful? Give feedback.
-
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
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
1.5 Integrity and Availability
and corresponding pages in other languages should be accessible.
time or plan for missing resources, and add a simple explanation if necessary.
1.6 Space
1.7 Punctuation Marks
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.
2 The Chinese edition specification
2.1 Space
2.1.1 Between Chinese and English
Positive:
Negative:
Specifically: For product terms, write them in the officially defined format.
2.1.2 Between Chinese and the digital
Positive:
Negative:
2.1.3 Between the unit and the digital
Positive:
Negative:
Specifically, there is no need to add spaces between degrees, percentages, and numbers:
Positive:
Negative:
2.1.4 No spaces between full width punctuation and other characters
Positive:
Negative:
2.1.5 Spaces between links
Usage:
Compared usage pairs:
2.2 Punctuation marks
2.2.1 Do not repeat punctuation marks
Positive:
Negative:
Full angle and half angle
2.2.2 Use full width Chinese punctuation
Positive:
Negative:
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:
Negative:
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:
Negative:
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:
Negative:
2.3.2 Inappropriate abbreviations
Do not use unconventional abbreviations.
Positive:
Negative:
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: 将"的"字都翻译出来，但是读起来很不顺畅
Positive: 去掉不必要的"的"字，就会简洁很多：
3.6.2 不必要的量词/冠词的翻译
英文一般比较严谨，当代表多个时，会使用复数名字，在翻译成中文时，一般不需要刻意把这种复数翻译出来。
在英文里，当单数可数名词时，前面一般会有“a”或“an”，但在中文里我们大多数时候是不用把“一个...”给翻译出来的。
示例：
State is a first-class citizen in Flink.
Negative: 将“a”翻译成“一个”
Positive: 去掉不必要的“一个”
虽然看起来没什么问题，但是这里的“一个”完全是多余的，去掉之后不但不会影响翻译效果，而且还会显得更加简洁。
3.7 专业术语
例如 "parallelism parameter" 不需要翻译成“并发参数”，而是应为“parallelism 属性”。
3.8 编写或者翻译文档时及时换行
编写文档时，在近似行字符数（120 chars）附近主动换行，方便 review 和 开发者阅读.
4 ASF Compliance
5 How to contribute
with prefix '[Improve][website] Improve {page-name}'.
It would be better to associate with the #3724 (Umbrella ISSUE ID)
ISSUE(you created) IDin the PR page.References
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!
Beta Was this translation helpful? Give feedback.
All reactions