Python公式ドキュメントで迷子にならないために
Pythonドキュメントの翻訳に携り始めて10年余り。 あの膨大な文字数のドキュメントのそこそこ広い範囲に目を通している @cocoatomo です。
Pythonドキュメントがどういう情報を提供するものなのかが伝わっていないように感じるときがあります。
https://twitter.com/cocoatomo/status/1394463409505067011
それで、自分の認識を整理することも兼て、Pythonドキュメントの読み方を書き出してみます。 それぞれで異議はあるかもしれませんが、各々のベストプラクティスを優先して大事にしてください。
ドキュメントは何のためのもの？
全ての本に目的と想定読者があるように、ドキュメントにも目的と想定読者があり、 残念ながらそこから外れた人が読むと分かりづらい意味の無いものに見えます。 それは筆者のリソースも無限には無いので仕方の無いことです。
ちなみに、これから書く目的や想定読者は私がそう理解したことであって、公式な裏打ちがあるわけではありません。
Python公式ドキュメントは、Pythonに関わる必要最低限の情報を正確に伝える目的があります。 そして、読者はある程度はコードを書いたり読んだりしたことがあるという条件が想定されています。 そのため、「実装例が少ない」「つまりどういうことか分からない」「この用語が分からない」という不満が出てくるのも自然なことです。
Python公式ドキュメントが取り零している部分は、きっと他のブログや勉強会の発表で解説されるでしょう。 OSSのコミュニティというのはそういう活動がなされるところだと、私は期待しています。
Start Python Clubで発表した話
お久しぶりです @cocoatomo です。 余裕が無くて手を付けられていませんでしたが、1年ぶりくらいにブログ記事を書きます。
みんなのPython勉強会#68
時間が過ぎてしまいましたが、4/14 (水) に Python ドキュメント日本語訳プロジェクトについての講演をしてきました。 この講演には Python コミュニティの1つである Start Python Club さんから登壇のお声があり、そろそろコミュニティーでの活動を再開したい気持ちもあったので、喜んでお誘いを受けました。
みんなのPython勉強会#68 では、私が責任者になっている「Python ドキュメント日本語訳プロジェクト」の概要を話してきました。 Python ドキュメントを使っている人はそれなりには居るとは思いますが、どのように翻訳されているとか、どんな事を考えながら翻訳しているかについてはなかなか知られていません。 そういった実状が広く知られ、縁の下の力持ちの方々の存在感を上げるためにこの勉強会は多いに有り難い機会でした。
発表資料
勉強会に参加できなかった方、勉強会を 発表で使ったスライドやQ&Aの記録をこちらで公開しておきます。
発表スライド
po4a+Zanataでpoetryのドキュメント翻訳
どうも横滑りのプロ @cocoatomo です. poetry のドキュメントを精読のために翻訳をしようとしたら, lunr-languages に PR を送っていました.
精読目的の翻訳
自分が技術文書を翻訳する目的の高い割合を占めるのが「精読」です. Python 公式ドキュメント や Pipenv のドキュメント の翻訳の目的はだいたい「精読」のためです.
https://twitter.com/cocoatomo/status/1083875818189684736
Python における依存関係管理, パッケージング
正直に言うと, 今でも Python のパッケージングまわりのことをちゃんと分かっていません. setup.py 書くたびにあちこち調べて python setup.py install を何度も試して, なんとか書いているレベルです.
最近, Python の依存関係管理やパッケージングまわりが賑やかなようで, その文脈で poetry というツール名を聞くようになり, 勉強がてらドキュメントを翻訳することにしました.
2019年の抱負
何人かが2019年の抱負を書いてるのを見て書きたくなりました.
去年は抱負を決めてなかったので振り返りは無しです.
あ, そうだ. docutils-stubs という型情報パッケージのリリースに少なからず貢献したのでした. 今まで自分の趣味のためのものくらいしか公開してなかったので, このパッケージを通して Sphinx という, 自分以外の人が使う文書作成ツールに貢献した実績が積め, とても嬉しいです. (ref. https://tk0miya.hatenablog.com/entry/2019/01/03/150221)
抱負のリスト
分野ごとに分けて抱負を決めます.
- 健康: 肉体的にも精神的にも健康で過ごす
- そのために, 定期的に運動する (ウォーキング, 水泳など)
- 体重, 体組成の計測 (#やせたーん 復帰)
- 技術
- 必要だと分かったものはすぐに学習を始める (これが最低限)
- 将来を見越して必要だと思うものを見付ける
- OSS活動
- Python公式ドキュメントの翻訳率を80%以上にし, 維持する
- 翻訳者が増えるようなリクルート活動をしていく (まずはハンズオンの復活)
- 執筆活動
- 本を1冊出す (のが確実になるくらい原稿を書き上げたい. ちょっとひよった.)
さて1年後はどんな自分になっているのでしょう.
転職しました
7年余り務めた NT [1] を辞め, 12月から新しい会社で働きます. 最終出社日は10月31日で, 11月いっぱいは有休消化期間でした. 12月1日と2日は土日なので実際に働き出すのは3日からになります.
前職にて
NT が立ち上がる少し前から, 一緒に仕事をするメンバーたちのいるチームに参加し, 会社の設立や成長を舞台として多くの経験を積むことができました.
参加したばかりの頃は, 今の自身から見ても非常に未熟で「よく給料もらえてたな」と思ってしまうほどです. 良いように捉えるなら, その頃に比べてかなり成長したのだと言えるでしょう. もちろん自分一人の力で成長したのではなく, レベルの高い先輩たちに相談に乗ってもらったり, 時には厳しい言葉を頂いたりしたおかげで, ここまで成長できました. そういった人に恵まれた環境が前職の良いところです.
Python 3.7 ドキュメント翻訳プロジェクト始動!!
Python 3.7 が 2018/06/27 にリリースされ, それを受けて 3.7 の翻訳プロジェクトも 2018/06/30 に開始しました.
1つ前の Python 3.6 の翻訳プロジェクトが開始したのが 2017/02/17 だったので, 約1年3ヶ月ぶりの新プロジェクトということになります. (当時の記事: Python 3.6 ドキュメント翻訳プロジェクト始動!!)
PEP 545 – Python Documentation Translations が出てから初めての新規プロジェクトということで作業手順の刷新に手間取りましたが, 無事に安定した手順が作れ, 問題無くプロジェクトを開始できています.
新バージョンとは言え, ドキュメントの大部分は Python 3.6 のときと大きく変わってはいないので, 開始時点で日本語への翻訳率は 80% を越えています! ドキュメントを参照される方にとって, 最低限の役に立つ状態になっていると思います.
まずは Python 3.7 の新機能についてのところを訳していて, 現時点で翻訳率は 25% を越えています. このペースなら今月中にはあらかた訳せるものと思います. まぁ, どうなるか分からないけど.
翻訳への指摘について
最近, 嬉しいことに翻訳についての指摘をもらえることがあります. たいていは issue で指摘をもらうのですが pull request の場合も増えてきました. プログラマが読むドキュメントなので, それが自然なのでしょう.
せっかくの有難い指摘なのですが, これまでの経緯もあって, issue は python-doc-ja レポジトリに出して欲しいです.
python-docs-ja レポジトリは現状では単なる .po ファイル置き場で, Transifex からダウンロードしてきた翻訳ファイルを保存するためだけのものとしています. Transifex へのアップロードは行っていません. こちらに pull request をもらうこともありますが, それをマージしても次回のダウンロードで上書きされてしまいます. 今までもらった PR は手動で Transifex に反映しています.
issue & pull request からのマージ, Transifex への反映という流れを作ろうという構想はあるので, 気長に待っていてください.
結び
今後も気付いた問題の指摘や翻訳の提案, さらには翻訳者としてプロジェクトに参加をしてもらえるととても助かります.
そこまで直接的な貢献は無くとも, このドキュメントを利用して, いいツールやプログラムを実装していってもらえたら嬉しいです.
しばらくはこの活動をほそぼそと続けていくつもりなので, どうぞよろしく.
Python 日本語ドキュメントのお引越し
Python ドキュメント日本語訳プロジェクトの翻訳者で管理者の cocoatomo です.
Note
Python ドキュメント日本語訳プロジェクトは, 常にあらゆる経路でのコントリビュートをお待ちしております. 「訳文の提出」のような直接的だけど労力のかかる貢献の他にも 「誤植報告」「読みづらい箇所を Twitter でつぶやく」 「読んだ感想を Twitter でつぶやく」などの方法があります.
翻訳をしたい方は Transifex から参加申請を, 誤植報告する方は GitHub の issue から issue 登録を, 何かしら Twitter でつぶやく人は @cocoatomo 宛てか, #pythondocja を付けてつぶやいてもらえると嬉しいです.
tl;dr
- 日本語ドキュメントが docs.python.org へお引越し
- 管理作業の自動化に成功
- Continuous Delivery の知見が増えた
経緯
Python を使っている人のほとんどは「Python の公式ドキュメント」と言われて思い当たる Web 上のドキュメントがあるはずです. それと意識していなくても検索してそのページに辿り着いた人もいるはずです.
「Python で分からないことがあって検索した」「Python のパッケージの使い方を知る」 「この Python の挙動が仕様なのか調べる」など色々な目的で閲覧され, Python を使った開発を少なからず支えています.
オリジナルの英語版が https://docs.python.org/3/ で公開されていて, それが日本語に翻訳されたものが https://docs.python.jp/3/ で公開されています. 日本語が母国語の人達なら, 英語に慣れないうちは日本語を読む方が10倍くらい速く内容を理解できると思います.
『文学部唯野教授』の感想
これは pyspa Advent Calendar 2017 の18日目の記事です.
読書と私
子供の頃はそれなりにたくさん本を読んでました. 小説 (特に推理小説), 科学の本, 数学の本, 宇宙の本, その他雑多に, 1日あたり1冊くらいのペースで読んでいたと思います. 小説は自分の生活では体験できないことを疑似体験できるのが楽しくて読んでいました.
大学に入ったあたりから, 周囲の人間の方が面白人間のサンプルとして質が高くなったためか あまり小説を読まなくなりました.
翻訳作業って何をするの?
前回 に引き続き Python ドキュメントの翻訳プロジェクトの話をします. 今回は翻訳プロジェクトが実際にはどんなふうに進められているかについて解説しましょう.
「翻訳作業」は形式的な見方をすれば, 英語で書かれた文章を日本語の文章に変換することです. CPython では, 英語の原文は Sphinx で作られていて CPython と一緒に GitHub レポジトリ で管理されています. では, これをフォークしてソースファイルを書き換えてビルドし, どこかのサーバーでホストすれば翻訳は完了でしょうか?
いいえ. 翻訳した時点では作業は完了したように思えるかもしれませんが, 原文はどんどん更新されていきます. その理由は CPython への文法の追加かもしれませんし, 新しい標準ライブラリの追加かもしれません. またドキュメントの誤りの訂正かもしれません. いずれにせよ訳文も原文の更新に追い付く必要があるでしょう. そのとき原文を直接訳文で置き換えてしまっていては, 原文の更新を管理するのが難しくなるでしょう.
Python 3.6 ドキュメント翻訳プロジェクト始動!!
Python 3.6 が 2016/12/23 にリリースされ, 日本でも リリースパーティー が開催されました.
Python は手厚いドキュメントがあることで有名 (?) で, そのドキュメントを日本語へ翻訳するプロジェクトも行われています. みなさんも Python について Web 検索したときにこのページを見たことがあると思います.
この日本語のドキュメントを作っているのが, その翻訳プロジェクトです.
翻訳プロジェクトでは, Python 2 系と Python 3 系の最新のドキュメントを翻訳対象としています. (過去のバージョンはプロジェクトの人手的に対象にできていません.)
本家の GitHub レポジトリの移行 (作り直し) が終わるのを待っていたのもあって, Python 3.6 がリリースから日が経ってしまいましたが, 準備を整え 2017/02/17 に翻訳プロジェクトを開始しました.
https://twitter.com/cocoatomo/status/832389004116963328
前バージョンから変わっていない文章は既に翻訳が適用されているので, 現在翻訳率は 87% です. 残りの未訳の部分もこれからドンドン翻訳していくのでお楽しみに.
Python 3.6 の新機能は色々あるのですが, 自分が興味のある「変数アノテーション」の部分を翻訳しようと思っています.
あ, それと翻訳に興味のある方, 協力してくださる方はいつでも大歓迎です. 普段 Python を使っている方, 翻訳そのものに興味のある方, 何かの形で OSS 活動に関わってみたい方などなどお待ちしてます!! 誤植報告もお気軽に. GitHub の issue でも, ハッシュタグ #pythondocja を付けて Twitter でつぶやくのでも構いません.
GitHub: https://github.com/python-doc-ja/python-doc-ja/
次の記事では, 翻訳作業って何をするの? という疑問に答える予定です.
それでは.