"Vim ドキュメント翻訳者の手引き" を改善したい
obcat opened this issue · comments
Problem
Wiki の Vim ドキュメント翻訳者の手引き が少し見づらいと感じます。
Suggestion
とりあえず次のような改善を加えて体裁を整えたいです。
- 適切に見出し (
#、##、...) を追加する - 意見やコメント部分を本文と差別化する
- 適切な例を追加する
特に見出しがあると特定の部分をリンクで参照しやすくなるので良いんじゃないかなと思います。
よろしければ私がやろうかなと思っているのですが、更新してもいいでしょうか?
Wiki には PR できないみたいなので、直接更新してからここに事後報告するという形になるとは思いますが…
一度体裁改訂版をここに例示して、調整してもいいかもですね
ありがとうございます。そうですね。
一応こんな感じにしようかなと考えています (実はモチベがあるうちにと思ってもうローカルでやり始めています 😇)
Vim ドキュメント翻訳者の手引き
はじめに
公式ヘルプの以下の場所にヘルプの書き方が記載されている。参照すること。
-
:h help-writing(翻訳ヘルプに限らない一般的な) ヘルプの書式について。
-
:h help-translated翻訳ヘルプを作成する際の注意事項。
文体
ユーザーマニュアルでは敬体 (ですます調) を用いる。
リファレンスマニュアルでは敬体と常体 (だである調) のどちらを用いても構わない。現状では両方が混在している。少なくとも、1 つのファイルではどちらかに統一しておきたい。
敬体を用いる場合でも、以下の場所では常体を用いること。
-
見出し
プラグインを使う ---------------- まず、プラグイン自身のドキュメントを読んで、動作条件を確認してください。 -
短い箇条書き
プラグインの追加は以下の手順で行います: 1. プラグインを入手する 2. 正しいディレクトリにコピーする
-
サンプルコードのコメント
:smile *:smile* ユーザーを幸せにします。例: > " 10000 回幸せにする for i in range(10000) smile endfor
命令形の翻訳
リファレンスマニュアルなので、命令しているというよりは操作の手順を簡潔に述べているだけであって、特に命令形だからという意識はしなくて良い。
...
何の了承も得てませんが勝手に更新しました 😇
diff: https://github.com/vim-jp/vimdoc-ja-working/wiki/Guide/_compare/3ddfd3a%5E...3ddfd3a
主に体裁を整えただけです。ちょっとメモを追加したり文章に手を加えたりはしましたが、項目を消したりはしてませんし内容としては変わってない… はずです
何かまずい点があったら revert しますので教えて下さい 🙇
半角空白を明示する部分で ␣ を使っていたところを _ に変更しているようですが、何か理由ありますか？
半角空白を明示する部分で ␣ を使っていたところを _ に変更しているようですが、何か理由ありますか？
たしか変更したきっかけは文章を書き直すときに ␣ をコピペするのが手間だったからだと記憶しています。で「_ のほうが見た目がすっきりしていて見やすいな」と思ったのでそのままにしました。
␣ のままにしておいたほうがよかったでしょうか…?
␣ は空白を表すための記号なので、元の文を書いたときはわざわざこの記号を使いました。
_ だと半角空白の代わりに使っているのか本当の _ なのかが注釈を読まないと分からないのがよくないと思います。
␣は空白を表すための記号
あー、それは知らなかったです… 注釈の必要性に関してはどちらも同じだと思っていました (知らなかったので…)
␣ に戻しておきます🙇
ありがとうございます。よく考えたら _ だとスペースが 2 個以上連続する場合に文字どうしが繋がったように見えてしまって分かりづらくなりますね。␣ にセリフっぽいものが付いているのはそうならないようにするためか。勉強になりました。
行頭の < に関する、このような記述を加えたいと思っています:
こちらのルール:
ただしコードブロックの後ろが空行の場合は、そこに < を追加する:
を追加することが目的です。いかがでしょうか?
上記の新ルール:
ただしコードブロックの後ろが空行の場合は、そこに < を追加する:
ですが、やっぱり微妙な気がしてきたので、この部分の提案は取り下げます。
理由: 原文に更新があって < 始まりでなくなったとき、余計な < を消す必要がありますが、< を空行、つまり更新箇所と別の行に追加していた場合、< の存在に気づけず消し忘れる可能性あります。一方で二重 (<<) になっていれば存在に気づきやすいので消し忘れる可能性は低いんじゃないかな、と思ったからです。
その他の変更 (例の追加など) は有用だと思うので、適用してもいいかなと思っています。
ちょっと手を加えてこんな感じになりました:
- 空行がある場合の新ルールを削除しました。
- 空行がある場合も
<を二重にすることと、その理由 (上記のもの) を追記しました。
何か意見がありましたら教えてください。