公式ドキュメントの読み方
「公式ドキュメントを読め」というのが急に話題になっていたので自分なりに整理してみました。
注意: そんなに真面目に推敲していません。フィーリングで書いているので実態に即してない部分もあるかも……
公式ドキュメントとは何か
あなたが使おうとしている道具 (ライブラリ、フレームワーク、プログラミング言語、ミドルウェア、コマンドラインツール、etc.)[1] は必ず誰かによって作られています。ある程度成熟した道具であれば通常、その作った人・組織自身によって公開されているドキュメントがあるはずです。これが公式ドキュメントです。
公式ドキュメントは、OSSにおいてはソースコードと双璧をなす最も信頼できる資料のひとつです。ソースコードが非公開の場合は通常、公式ドキュメントが最も信頼できる資料でしょう。 (以降はOSSを主に想定して説明します)
たとえば……
- Python のソースコードはGitHub上にあり、公式ドキュメントは公式サイトの下にあります。日本語版ドキュメントも現在は公式サイトの下にあります。
- Ruby on Rails のソースコードはGitHub上にあり、公式ドキュメントは公式サイトの下 (Guides) / (API) にあります。公式ドキュメントのうちGuidesはYassLab (株) により日本語訳が提供されています。
-
GNU gettext のソースコードはGNU Savannah上 にあり、公式ドキュメントは公式サイトの下にあります。日本語は存在しないようです。
- 日本語版がないときは機械翻訳を使う手もあります。大抵の場合、読まないよりも10000倍有益です。
- FactoryBot には公式ドキュメントのための独立したページはありませんが、ソースコード内の README.md や GETTING_STARTED.md が公式ドキュメントの役割を果たしています。
なぜ他の文書よりも公式ドキュメントを見るべきなのか
原則として、公式ドキュメントを他の文書より優先するのがよいでしょう。理由は以下の通りです。
信頼性
作者か作者の意図を知っている人が公開しているので、大まかには信頼性が高いことが期待されます。特に、(意図しないという意味での)間違った使い方を紹介することは稀でしょう。意図しない使い方が常に悪いわけではないですが、「たまたま動いているだけ」という危険な状態に突入することも多いので注意が必要です。
百戦錬磨
よく使われているライブラリの良いところのひとつは、多くの人が多くの条件下で使うことにより潜在的なバグがより多く発見され潰されていることです。公式ドキュメントにも同じことが言える可能性があります。ひとりの経験に基づいて書かれたブログ記事よりも、落とし穴が少ないことが期待されます。
なぜ実装よりも公式ドキュメントを見るべきなのか
OSSではソースコードを読むことができます。しかしソースコードがあれば公式ドキュメントがなくてよいわけではありません。ソースコードと公式ドキュメントは相補的であり、どちらかで代替できるものではありません。
必要な情報へのショートカット
できるだけ少ない手間で情報を手に入れるに越したことはありません。特に、誰もが必要とするような情報にショートカットを提供するのは理にかなっています。実装に含まれないショートカットとしてたとえば以下のようなものがあります。
- Getting Started と Tutorial。実際にライブラリを使ってみるまでの手順を整理したもの。通常 Getting Started では使い道をユーザーが選び、 Tutorial ではドキュメント側で設定された練習用のアプリケーションを通して使い方を学ぶ。
- Concepts。ライブラリが提供する機能を俯瞰したもの。
規約の表明
大抵のライブラリは一回ダウンロードして終わりではありません。更新によって実装が変わることがあります。(ネットワーク越しで使うものの場合は特に)互換品が登場することもあります。これらが全く同じ挙動をすることはまずありません。ライブラリが想定していない使い方をしていた場合、ライブラリのバグ修正で無慈悲にもアプリケーションが壊れる…… といった悲しい事件はそれなりにあります。
私たちはこれを100%防ぐ術を持ち合わせていません[2]が、想定された使い方がどんなものなのか(実装の外に)書いておくだけでだいぶ違います。それは通常はAPIドキュメンテーションという形で現れます。 (自動テストや形式仕様という形で記述されることもあります) これは実装からは読み取れないことです。
公式ドキュメントの読み方
公式ドキュメントと一口に言っても色々あります。大まかには以下のような内容に分かれていると考えていいかなと思います。
-
Getting Started: 今すぐライブラリを実用したい人向けの手順。READMEの一番最初に書いてあることも多い。
- セットアップが終わったらExamplesやAPI Referenceを見ながら作業する。
-
Tutorial: 先にライブラリを手に馴染ませたい人向けの手順。Getting Startedからいきなり使うよりも見落しが減るかもしれない。だいたいTODOアプリを作ったりとかする。
- 終わったらGetting Startedに戻って実際のアプリケーションに組み込む。
-
Concepts: 手を動かすのではなく読み物。
- DESIGN.md とかもこれに類するが、ライブラリ自体の開発者向けを想定しているものもあり、粒度はまちまち。
- API Referenceと違って巨大なライブラリでも人類が通しで読める分量になっている。
-
Examples: コード例。
- ぴったりのがあると無茶苦茶役に立つ。
- ほぼそのまま動かせるようになっている場合も多く、ソースコード外のセットアップが理由でうまく動かないときはExamplesとの比較をすることで問題が解決することもある。
- GitHubのソースコード中に
examples/みたいなディレクトリが切られて、そこに直接リンクが貼られていることも多い。
-
API Reference: 名前の通り。
- 普通はコメントや型定義から生成するのでサイトマップ上も扱いが違うことがある。 RubyDoc.info, docs.rs, pkg.go.dev のように横断的なホスティングサイトがある場合もある。
- サイズにもよるが、普通はこれを通しでは読まない。
- 辞書として使う。
大きなプロジェクトだと、公式サイトのヘッダーから飛べることが多いです。
小さいプロジェクトだとGitHubで完結していることが多いです。 README.md から各ドキュメントへのリンクが貼られていることも多いです。 README.md に全部詰め込んでいる場合も。
公式ドキュメントは万能ではない
ここまで公式ドキュメントの利点を紹介しました。残念ながら、公式ドキュメントは万能ではありません。
優れた実装が優れたドキュメントを持たないこともある
優れたドキュメントを持つことはライブラリの価値を確実に引き上げます。しかし、それを上回る価値を提供できていれば、必ずしもドキュメントがなくても優れたライブラリとして認められることもあります。優れた実装を書く能力と優れたドキュメントを書く能力は必ずしも同じではありませんから、そういうこともあります。
ドキュメントは古くなりがち
リソースを十分に抱えたプロジェクト、というものはなかなか存在しません。欲しい機能に対して足りないリソースを何とかやりくりをしているので、古くなったドキュメントの更新はしばしば後回しにされがちです。ですから、「情報が更新されていないせいで、もはや正しくない」という意味での「間違ったドキュメント」は公式ドキュメントにも沢山あります。これは非公式のブログ記事でも同じことですが、数多ある記事の中からならば最新の情報を見つけられる可能性もあるでしょう。
こんなとき、あなたに出来ることがもう1つあります。古くなった公式ドキュメントを書き換えて新しくすることです。これは非常に重要な貢献です。これをできるのは、実際に手を動かして問題に気付いたプログラマーだけです。そして、同じ部分を参照する人を救うのですから、これは立派に意義があることです。[3]
あれとそれの組み合わせ
公式ドキュメントがライブラリの掛け算に全く対応していないわけではありません。たとえばReactのドキュメントには React + TypeScript の使い方の説明 がありますし、Jestのドキュメントには Jest + Webpack のセットアップガイド があります。しかしこのような場合は特別で、2つの異なるライブラリを組み合わせたときの困難については公式ドキュメントには書いていないほうが多いでしょう。このようなとき、困っている同士がいればその情報は助けになるかもしれません。
問題からの逆引き
書いたコードに問題があるとき (要するにバグらせたとき) 、公式ドキュメントが直接助けになることはまれです。これは次のような理由によるものです。
- 問題はしばしばライブラリや環境の膨大な組み合わせの一例としてあらわれるもので、特定のライブラリの公式ドキュメントで網羅しきれる内容ではない。
- 問題の解決にまず必要なのは糸口の発見であり、そのためには情報の信頼性は必ずしも重要ではない。
問題が起きたときの解決の第一歩としては検索とQ&Aサイトが最強です。 (もちろん、情報源に頼らずに自分でできる調査もたくさんあります。)
取っ掛かりがつかめたあと、問題の原因をきちんと理解するときには、二大ソースであるソースコードと公式ドキュメントは再び最強の道具に返り咲きます。うまく道具を使い分けて、問題解決の達人になりましょう。
まとめ
- 多くの成熟したライブラリでは、公式ドキュメントは信頼性が高く有用な情報が集約されているため、優先的に参照するべきです。
- しかし、残念ながらそうではない場合もあります。公式ドキュメントか否か、はあくまで参考でしかないことを頭の片隅に置いておくといいでしょう。
- 公式ドキュメントと一口に言っても様々な内容からなります。うまく使い分けて必要な情報を発見しましょう。
関連
- ドキュメントの読み方といえば
- 本記事のきっかけになった議論
Discussion