Minor improvement to Chinese expression

[HtwoO]

I suggest you search the Chinese essay 论中文的常态与变态 by 余光中 and improve some of the expression in the Chinese documentation.

I'm writing this in English because I see the commit history are almost all in English.

[xen0n]

I personally object to doing this, because technical Chinese writing mostly does NOT benefit from the typical Chinese expression characteristics which are mostly implicit semantics that have to be inferred.

[xen0n]

Also see the natlang-style-guide doc in the website -- it is explicitly recommended to write in 欧化中文 whenever it's more appropriate to do so -- unambiguity is strictly more valuable to "language beauty" or "naturalness".

[xry111]

But for this specific case it seems improving the beauty won't affect unambiguity, so why not?

FWIW in some cases natural Chinese is more unambiguous than English. For example in the LFS book there are some "the test named test-something is known to fail" but I translate these phrases differently to "已知名为 test-something 的测试会失败" and "已知名为 test-something 的测试可能失败."

I do this because I'm a LFS editor and I'm pretty sure how to analysis them case by case. But in English they are just the same, and in the mail list there are occasionally complains saying "hey, you say test-something is known to fail but it does not fail for me."

[xen0n]

But for this specific case it seems improving the beauty won't affect unambiguity, so why not?

Let me explain more in another review... yesterday I was feeling a bit sick so I could only review on my phone.

FWIW in some cases natural Chinese is more unambiguous than English. For example in the LFS book there are some "the test named test-something is known to fail" but I translate these phrases differently to "已知名为 test-something 的测试会失败" and "已知名为 test-something 的测试可能失败."

I do this because I'm a LFS editor and I'm pretty sure how to analysis them case by case. But in English they are just the same, and in the mail list there are occasionally complains saying "hey, you say test-something is known to fail but it does not fail for me."

For the latter case, no they can be expressed differently: "it's known that the test case ... can fail" vs "it's known that the test case ... fails"; or maybe "the test case named ... is known to fail sometimes".

[xen0n]

Thanks for your contribution (even though we may disagree a lot about Chinese language usage or each other's true nationality).

Anyway, even if we're to style this technical website the literary or 余光中 way, there are far more places that needs editing: first of all the recommendation to use 欧化中文 must be reworded, then one would have to go through every single doc to remove 被 markers inferrable from context (e.g. animacy). If expressions like "一般被认为……的用户" or even "描述式" are considered eyesore, then something like "这些被捆绑的旧世界动态链接库，会先于新世界宿主系统提供的动态链接库，被搜索和加载。" would certainly be something burning from hell...

And, as you're touching the natlang-style-guide doc itself (which I didn't notice yesterday), I'd like to reiterate what I want to experiment with the particular writing style: to minimize possibility of confusion, and to objectively do that with explicit recommendation for gratuitous usage of grammatical markers / otherwise redundant information. I have seen and written technical docs in my previous job both in this way and not, and the team's experience is the "more natural / oral" versions require lots of back-and-forth communication to have ambiguities resolved, which is almost always the case; while the 欧化中文 docs by me mostly can be understood by anyone else without having to consult me.

So, in this patch's current shape, I'm likely to accept the last change with modification (changing your "具体的" to "生动的" which better matches the "deep structure" of my thoughts), but decline the other two. Thanks for sharing your thoughts again.

[xen0n]

This is a guide geared towards contributors, so trivial definitions (that could be looked up trivially) like "i18n" don't need explanation.

Also the meaning is changed in the wrong way: the original text says it's Chinese text of other articles that are covered for now, while after your tweak it's referring to this article itself.

[HtwoO]

Whether or not 本文 includes the future English version depends on the interpreter. Maybe 本项目 is better.

[xry111]

“本文目前只描述汉语文本的语言惯例”。

应该是这个意思。

[xen0n]

Maybe I'm a fake Chinese, but I find the changed version slightly more difficult to comprehend: what's the subject of "以为"? I meant the subject to be the conceptual "LoongArch insiders" (maybe I have to be more explicit about this) but after the change I think the subject becomes "the user" which is wrong.

[xen0n]

Again, semantic change. By "这一般是好事" I'm implying "not all of the consequences are beneficial", and indeed I'm following up with a concrete example of detrimental consequence, but after the change it seems the consequence is "100% bad instead of 100% good".

[xry111]

I'd say this change is wrong. Personally I don't think "some U.S. government agency has started to hack on LoongArch" a "good" thing. Maybe the others don't agree but "good" or not is highly subjective anyway.

[xen0n]

Okay this might be an interference from the English part of my brain (here "描述式" = "descriptive" = "生动的", but "描述式" != "生动的"). I literally thought for 5 minutes why "描述式" could be a problem...

[HtwoO]

Initially I only wanted to change this as it's obviously from "descriptive" in English, but a direct "translation" to Chinese is rather odd for Chinese readers. And I somehow think this alone is too small a change. Then I saw no glossary for "i18n" after greping in the project, so I made a few more changes.

[xen0n]

BTW, please think about the example I gave in the doc -- 「AM* 原子访存指令如果 rd 和 rj 的寄存器号相同，则触发指令不存在例外。」 where everyone already familiar with Loongson didn't have a problem comprehending it, but everyone reading about LoongArch for the first time had parsed the syntax in the wrong way. Sure, the LoongArch manual only mentioned 指令不存在例外 after the instructions (and this sentence), but you can see that some classes of ambiguities is impossible for experienced contributors to notice with conventional oral speech, so the extra information provided by 欧化中文 serves to objectively improve comprehension for everyone alike.

[HtwoO]

I understand that it is important to be accurate in technical writing. I personally also prefer unambiguity over beauty and naturalness when writing documentation. But in many cases we can write unambiguously and naturally.

The purpose of a documentation is to help readers understand the subject matter. In other words, the goal of an article is to communicate (although in many cases it's just one way, namely, authors -> readers). Thus many organizations now encourage people to use plain words in writing/speaking.

Writing naturally and concisely usually help readers understand the content better. Ideally technical documents should include a "prerequisites" paragraph to provide assumptions for further content for easier reproducibility at audience's end.

reference:
https://www.justice.gov/open/plain-writing-act
https://en.wikipedia.org/wiki/Corporate_jargon#Criticism
https://en.wikipedia.org/wiki/Wikipedia:Use_plain_English.

[xry111]

BTW, please think about the example I gave in the doc -- 「AM* 原子访存指令如果 rd 和 rj 的寄存器号相同，则触发指令不存在例外。」 where everyone already familiar with Loongson didn't have a problem comprehending it, but everyone reading about LoongArch for the first time had parsed the syntax in the wrong way. Sure, the LoongArch manual only mentioned 指令不存在例外 after the instructions (and this sentence), but you can see that some classes of ambiguities is impossible for experienced contributors to notice with conventional oral speech, so the extra information provided by 欧化中文 serves to objectively improve comprehension for everyone alike.

This sentence is certainly ambiguous even only considering the "normal" Chinese writing. And even the Loongson translator (I can reasonably assume he/she is familiar with LoongArch) could not understand this sentence so the initial version of the English manual was wrong here.