楽しいだけで十分です

ゆるくはじめる、OSSのドキュメント貢献のやり方

ドキュメントの修正などを中心にOSSコントリビュートをしている話をしたら、同僚のkymmt90から「せっかくだし、やり方をブログに書いたら？」とアドバイスをもらいました。確かに役立つ人もいるかも〜と思ったので書いてみます。

なぜコントリビュートするのか

ドキュメントのコントリビュートの方法を書く前に、それをすると何がうれしいのかを上げてみます。自分が思ってるものだと大きく2つです。

  • 人の役に立つ
  • OSSへのコントリビュートの入口に最適

人の役に立つ

コントリビュートすることで、本でいう正誤表を実際の内容に反映するところまで行うので、ドキュメントを読む人が正しい内容で理解できるようになります。メンテナと議論ができたり、感謝されることもうれしいことで、モチベーションを高める1要素になっています。

OSSへのコントリビュートの入口に最適

OSSへのコントリビュートというとバグを修正したり、機能追加したりという方がイメージしやすいと思います。ただ、今までコントリビュートしたことない人がいきなりそれをやるにはハードルが高いと感じます。コントリビュートするのに必要なステップは以下のような感じでしょうか。

  • コントリビュートしたいOSSを見つける (★)
  • 対象のOSSがホスティングされているツール(GitHubなど)の使い方を理解する (★)
  • 対象のOSSのコントリビュート方法を理解する (★)
  • 行いたいこと・既存のコードを理解して、実装をする
  • (多くの場合は英語で)変更内容を説明する・返答に対してコミュニケーションを取る (★)
  • マージしてもらう (★)

この中で、 (★) がついた部分に関してはドキュメントのコントリビュートでも経験できます。確かにドキュメント修正ができたからといって、バグ修正・機能追加ができるようになるまでには難易度の差があります。しかし、問題(=コントリビュートするということ)を分解して解決しやすくするアプローチを取る場合、ドキュメント修正はそこそこいい方法かなと考えています。

どうやってコントリビュートするか

本題のコントリビュートのやり方ですが、この辺りがわかってるとやりやすいと思う3点について書きます。(なお、GitHubにホスティングされているOSSを想定して書いてます)

  • 見つけ方
  • コントリビュートのやり方
  • 英語で修正内容を伝える方法

見つけ方

実際に自分がやっている方法としては、2つあります。

  • 自分の興味あるOSSのドキュメントを読む (オススメ)
  • OSSを写経する (あまりオススメはしない)

自分の興味あるOSSのドキュメントを読むは、なんの変哲もないやり方ですね。例えば、OSSのコントリビュートしたことない人でも、本を読んでいて「ここ間違えてないかな？」と思ったことがあると思います。それをPRにして直すイメージです。具体例として、Getting Startedを読んでる途中で見つけたり、Vue.jsのテスト方法の学習ガイドを読んでいて見つけたリンク切れを直したりしてます。普段ドキュメントを読む機会があると思うのですが、その時に「どこかに間違いがないかな？」と意識してみると意外と見つかると思います。

OSSを写経するは時間がかるのであまりオススメしないのですが、紹介しておきます。OSSの写経を始めたきっかけは、実際に使われるJSの実装方法や、ディレクトリ構成などを理解したくて、OSSをそっくり真似て作ればいいのではと思ってやっていました。実際に写経していく中で、コメントのtypoを見つけたり、ログ出力のtypoを見つけたりしました。修正対象を見つけるだけなら、写経しないでコードを読むだけでも見つけられそうなので、そういう意味ではやってみてもいいかもですね。

最後にテクニック的な話になりますが、PRを作る前に確認しておいた方がいいことがあります。マージしてもらうという観点から、コントリビュートを受け付けていること・メンテナがアクティブであることです。コントリビュートを受け付けていることに関しては、基本的には受けつけていると思います(僕自身は受け付けてないOSSを見たことない)。もし受け付けてない場合はREADMEなどに書いてあるんじゃないかなと思うので、一応確認しましょう。メンテナがアクティブなことに関しては、OpenになっているPR数と最終コミットの日付を見ましょう。OpenになっているPRが溜まっているのに、最終コミットの日付が1年以上前などの場合、PRを出してもマージしてもらえない可能性が上がります。

コントリビュートのやり方

修正対象を見つけている時点でだいたいのやりたいことは終わったようなものです。あとは以下の手順に沿ってPRを出してみましょう。なお、GitHubのforkのやり方がわからないという方は、GitHub のフォーク （fork） とプルリクエスト （pull request） の使い方 - akihiro kamijoを読んだり調べたりしましょう。

  1. CONTRIBUTING.md (コントリビュート方法のガイド)を読みましょう。こんな感じのものです: js-primer/CONTRIBUTING.md at master · asciidwango/js-primer。
  2. 過去のPRを見てみましょう (内容説明の言い回しを参考にするなど)
  3. とりあえず出してみましょう (無下にされることは多分ないはず。もし無下にされてしまったら、その時は気持ちを切り替えて次に行きましょう。)

英語で修正内容を伝える方法

英語が得意じゃない人にとってハードルになる部分だと思います。しかし、修正内容はコードでも説明しているので、あまり肩肘張らないでもいいと思います。例えば、typo修正くらいの単純な修正なら、ほとんど英語は書かないものでも大丈夫だと思います。説明が必要な場合でも、Google翻訳などを駆使すればなんとかなると思います。

まとめ

自分が実践しているOSSドキュメント貢献の方法を紹介しました。初めてのOSSコントリビュートだと、ドキュメント貢献でもハードルが高く感じてしまうかもですが、やってみると思ってたよりできると思います。

yinm

WRITTEN BY yinm

I'm a Frontend Engineer.