Improve contrib guide #311
Conversation
|
とあるOSSのReadme英語で書いた時は、後々ほぼ全部修正されました 👍 |
|
私の英語もそう上手くないので変な指摘もまざっているだろうことには注意してください |
fukatani
force-pushed
the
improve-contrib-guide
branch
from
34c8ada to
e2f97a1
Compare
丁寧に見てもらってありがとうございます。修正しました。（ほぼご提案をアプライした形です。） |
| @@ -97,8 +121,11 @@ $ python3 setup.py test -s tests.command_download_atcoder.DownloadAtCoderTest | |||
|
|
|||
| ## CI | |||
|
|
|||
| Travis CI will run automatically when you commit or send PR on `master` or `develop` branch. | |||
| The same test as that by `python3 setup.py test` is executed. | |||
There was a problem hiding this comment.
すっきりして良くなったように思います。
しかしまだもう一歩で、 "as that by ..." はなにか変です。
例えば the same thing as that by などで検索するとまったく使われていない表現であることが分かります https://www.google.com/search?q=%22the+same+thing+as+that+by%22
| 機能要求やバグ報告は気軽にしてください。 | ||
| コードを書くことだけが開発ではありません。 | ||
|
|
||
| ## pull requests / プルリクについて | ||
|
|
||
| PR is always welcome. |
There was a problem hiding this comment.
| PR is always welcome. |
ところでこれ消した方がいいかもしれない。
「プルリクは歓迎します」というのはそのようなことを滅多にしてこない日本人に対しての最速という性格があるので、その意味では英語に翻訳した場合は消えるべきです。
CONTRIBUTING.md
Outdated
| @@ -36,10 +51,19 @@ For other place, both English and Japanese are acceptable. | |||
|
|
|||
| ## philosophy of design / 設計の方針 | |||
|
|
|||
| **Our purpose is to help get a higher rank in programming contests.** | |||
| To make it possible, online-judge-tools automates *mistakable and cumbersome manual work*. | |||
There was a problem hiding this comment.
このあたり online-judge-tools とそのまま書いてるけど、 this program とかの方が自然だったりしないかな？ (実際にどうなのかは私も知りません)
There was a problem hiding this comment.
https://github.com/Microsoft/LightGBM
読むとLightGBMということばが何回か出てきます。
There was a problem hiding this comment.
たしかに出てきてはいますが、それは根拠として弱いように感じます。
readmeの一番上の部分で書かれる文章はすこし性質が違うためです。また LightGBM v2 LightGBM Slack team などという形での出現は固有名詞であるため数え入れるべきではありません。
There was a problem hiding this comment.
https://github.com/tensorflow/tensorflow
tensorflowと何度も書いてます。
CONTRIBUTING.md
Outdated
|
|
||
| Also, we are focusing on *online-judge-tools does not cause the penalties*. | ||
| Since online-judge-tools does web scraping, the behavior is unstable. | ||
| To prevent penalties under this condition, *we avoid to supports the features which is prone to malfunction* and *make it easy to notice malfunction if malfunction is occured*. |
There was a problem hiding this comment.
conditionって言うと「条件」とか「状態」という雰囲気がつよくて適当ではなさそう？ https://ejje.weblio.jp/content/condition*we avoid to supports the features後ろの強調が*make it easy ...なのでこっちも*avoid to ...にしたい。 s/supports/support/the features which is prone to malfunctionもうちょっと平たく書きたい気がする。prone はどれくらいよく使われる語なんでしょう (私も知らない)。 s/is/are/notice malfunction if malfunction is occuredこれmalfuctionを2回書いてるのやめたい
CONTRIBUTING.md
Outdated
| Since online-judge-tools does web scraping, the behavior is unstable. | ||
| To prevent penalties under this condition, *we avoid to supports the features which is prone to malfunction* and *make it easy to notice malfunction if malfunction is occured*. | ||
| For example, this program pretty-prints the downloaded sample cases. | ||
| If such a printing does not exist, false acquisition of the sample cases causes a considerable time loss. |
There was a problem hiding this comment.
false acquisition なんかもうちょっと平易に書きたい
There was a problem hiding this comment.
Sample case acquisition errorはどうでしょう？
There was a problem hiding this comment.
もう一声ほしいです。
元の日本語が「サンプルケースの取得ミス」ですが、false acquisition of the sample cases だと 「サンプルケースの偽獲得」ぐらいの雰囲気でした。今回の Sample case acquisition error でもまだ「サンプルケース-獲得エラー」ぐらいの固い感じが残っているように思います。
There was a problem hiding this comment.
代案思いつかないので、このままにするか、一旦ここは英訳せずに消します。
| - Write code easy to understand. | ||
| - Don't make diff which is unnecessary for the purpose of PR. | ||
| - Split commits appropriately. | ||
| - Comment on the code where you are not confident of. |
There was a problem hiding this comment.
https://help.duda.co/hc/en-us/articles/115000553108-I-have-custom-code-where-do-I-place-it-
にという文章があります。
When getting the code from another source, it's important to understand where that code must be placed.
There was a problem hiding this comment.
その例文は根拠としては不適切に見えます。なぜなら where の型が違います。
where that code must be placed の where は全体で名詞となる部分を作るために働いていますが、元々話題にしていた文の where はそうではありません。
There was a problem hiding this comment.
https://www.cs.utah.edu/~germain/PPS/Topics/commenting.html
Any "tricky" code where it is not immediately obvious what you are trying to accomplish, should have comments right above it or on the same line with it.
このwhereはどうでしょう。なお、型とか忘れてます。
| `master` `develop` に関する commit や pull request について CI が走ります。 | ||
| `python3 setup.py test` の実行でも同等の処理が行われるように設定されているので、手元でこれを実行しているなら気にする必要はありません。 | ||
| `python3 setup.py test` の実行によるものと同等のテストが行われます。 |
|
修正されたのを元にもう一度見直してコメントを付けました。再度よろしくお願いします |
|
すいませんが、英語についてあまりディスカッションする気はありませんので、今コメントついて修正できてない箇所は一旦取り消す価値でよいでしょうか？ |
|
はい。それでも構いません |
|
(「日本語がないところに英語が増えるのなら質に関わらず価値がある」「すでにある日本語の翻訳として機械翻訳と変わらない質の英語を書くのでは価値がなく、むしろ管理対象が増える分だけ損である」というのが私の立場です。後者を無視して前者の一部だけを過去に伝えてしまっていたような気がしていて、これにより面倒をさせてしまったように思います。ごめんなさい。) |
|
いえいえ、こちらこそ中途半端なPRでレビューの手間を増やしてしまいすいませんです 😶 。 |
philosophy of design |
|
mergeしました。お疲れさまです。ありがとうございました。 |
|
@fukatani これ kfaRabi さんの Toph の話を進めるのに役に立ちます。感謝 |
少し、英訳＋日本語も修正。