Python公式ドキュメントで迷子にならないために

Pythonドキュメントの翻訳に携り始めて10年余り。 あの膨大な文字数のドキュメントのそこそこ広い範囲に目を通している @cocoatomo です。

Pythonドキュメントがどういう情報を提供するものなのかが伝わっていないように感じるときがあります。

それで、自分の認識を整理することも兼て、Pythonドキュメントの読み方を書き出してみます。 それぞれで異議はあるかもしれませんが、各々のベストプラクティスを優先して大事にしてください。

ドキュメントは何のためのもの?

全ての本に目的と想定読者があるように、ドキュメントにも目的と想定読者があり、 残念ながらそこから外れた人が読むと分かりづらい意味の無いものに見えます。 それは筆者のリソースも無限には無いので仕方の無いことです。

ちなみに、これから書く目的や想定読者は私がそう理解したことであって、公式な裏打ちがあるわけではありません。

Python公式ドキュメントは、Pythonに関わる必要最低限の情報を正確に伝える目的があります。 そして、読者はある程度はコードを書いたり読んだりしたことがあるという条件が想定されています。 そのため、「実装例が少ない」「つまりどういうことか分からない」「この用語が分からない」という不満が出てくるのも自然なことです。

Python公式ドキュメントが取り零している部分は、きっと他のブログや勉強会の発表で解説されるでしょう。 OSSのコミュニティというのはそういう活動がなされるところだと、私は期待しています。

ドキュメントの内訳

Pythonドキュメントの内容はいくつかの章で構成されています。 章によって内容のレベルがバラバラなので、レベルに沿って章の分類をしてみます。

Python初心者向け

これらは、全てのPythonユーザーが読んでおいて欲しいものであり、特に初心者が最初に目を通しておくと良いものです。 ただし、ライブラリーリファレンスについては、知りたい好きなライブラリを選んで読んでください。 (全部を読むには何十日分の時間を消費する覚悟が必要です!)

Pythonに慣れている人向け

これらは特にPythonを 使う 人が必要とするものです。 既存のライブラリを駆使して、効率良く、高品質のプロダクトを作るために役に立ちます。

Pythonを深く知りたい人向け

これらはPythonを 作る / 拡張する 人が必要とするものです。 新しいライブラリを 作り / 広く配布 したり、Pythonの体内を 覗き / 深い理解 を得るのに役に立ちます。

今はまだ理解できなくても、時間をかけて順々に理解を積み重ねていけば分かるようになると思います。 (それくらいコードが綺麗ということですね。)

調べたいものがあるとき

  • 会話や文章の中に出てきた専門用語が分からないとき

    用語集 を検索する

    もし、Pythonだけに関わらないIT界隈の専門用語であれば、書籍やブログを検索して勉強しましょう

  • コードを読んでいて、何が書かれているのか分からない、または何故このコードが動くのか分からないとき

    言語リファレンス を読む

    それでも分からないときは分かりそうな人に相談しましょう

  • こんなライブラリがあるといいなと思ったとき

    まずは ライブラリーリファレンス を読みましょう 簡単に思い付く「あると便利なライブラリ」は標準ライブラリとして実装されていることがあります

  • ライブラリの使い方が分からないとき

    まずは ライブラリーリファレンス を読みましょう

    ドキュメントに書いていないことは、今あれやこれやとたくさん出ている書籍やブログを当たりましょう

ドキュメントに物申す

Python日本語訳ドキュメントを利用していて、色々言いたくなるときもあるでしょう。 それでも、安心してください。PythonはOSSです。意見を届ける方法があります。

終わりに

Pythonドキュメントの日本語訳に参加して10年余り、どう翻訳すれば内容が伝わるように考えながら訳文を作っています。 せっかく情報量の多いドキュメントなのだから、より価値を感じてもらいたくてこの記事を書いてみました。 情報量が多く迷い込むこともあるドキュメントの森の中で道を見付けてもらえたら嬉しいです。

この記事を書く一番のきっかけになったのは PyQのこの記事 です。 PyQ はPythonを仕事で使っている人達が作った、Pythonの勉強に良いサービスです。興味があれば PyQ での学習も考えてみてください。

それでは。