公開した自作OSSを有名にしたいすべてのOSS開発者が実践すべきこと
概要
こんにちは。フリーランスとして活動している加藤です。
さて、この記事ではタイトルのとおり、自分で作成したOSSライブラリなどをGitHubやその他のリポジトリで公開した際に、どうすればより多くの人々に自分が開発したソフトウェアを認知してもらい、そしてどうすれば継続して関わってもらえるのかについて書いていきます。
なぜこの記事を書こうと思ったのかというと、とても興味深いソフトウェアを開発しているにもかかわらず、人々に認知されず閑散としているGitHubリポジトリを多く見てきたからです。
また、私自身の経験として、公開した自作のOSSライブラリがまったく伸びない時期がありました。自分で作ったソフトウェアを世の中に出すのであれば、より多くの人々に認知されてより多くの人に使ってもらいたいですよね。
そうした時期に紆余曲折しながらも様々な方法を試行錯誤し、どうすれば他の開発者に自分が作ったソフトウェアを使ってもらえるのか数年間研究しました。そして、最近になってその努力が実を結んだのか、今年の始めに開発を開始したDart/Flutterで使用できるライブラリtwitter_api_v2がFlutterコミュニティの多くの開発者に注目され、公式Twitterの開発者向けページに掲載されたばかりか、ついにはTwitterDevJPの公式スペースにメインスピーカーとして招待されるまでに至りました。
ここまでの自分の歩みを振り返ってみて、注目されるソフトウェアとそうではないソフトウェアにはどのような違いがあるのかが見えてきたような気がしますので、若輩者ではありますが皆さんに共有したいと思います。
注目されにくいソフトウェアの特徴
まず、他の開発者に注目されにくいソフトウェアの特徴を明確にしておきたいと思います。
なぜなら、次に挙げる項目は一見すると当たり前のことでありながら、伸び悩んでいる多くの開発リポジトリで見過ごされていることであるためです。裏を返せば、次に挙げる項目を改善することで他の開発者に注目される確率を格段に上げることができます。
重要度の高い順に列挙します。
- READMEをはじめとした基本的なドキュメントが整備されていない
- ドキュメントが英語圏向けにローカライズされていない
- 開発だけが行われ、適切な宣伝がされていない
- ソースコードの質が低い
- テストコードが存在しない、または極端に少ない
しかし、次の項目に該当する場合はどのようにしても人々の注目を集めることは難しいので、上記の項目を改善しても大きな変化はないでしょう。
- 開発言語や分野がマイナーであり、プラットフォームやコミュニティの人口が少ない
- そもそも需要がない
さて、注目されにくいソフトウェアの特徴がなんとなくわかったところで、改善可能な項目について順番に説明していきます。
READMEをはじめとした基本的なドキュメントが整備されていない
まず、率直に言わせていただくと、必要最低限のドキュメントが整備されていないのは論外です。
特にREADMEはGitHubといった開発リポジトリにアクセスした際に一番最初に開発者の目に入るドキュメントであり、そのリポジトリで開発されているソフトウェアの説明書であり看板です。そのドキュメントが整備されていないというのは、リポジトリを見てくれた他の開発者に対して使っていただかなくて結構ですと言っているのと同じです。
これはソフトウェアの使用者側の視点に立つとわかりやすいのですが、開発の目的も使い方もわからない製品に触れることはまずありませんよね。例えば、実世界で考えてみても取扱説明書といった資料がない製品が消費者に選ばれることはまずないでしょう。もしリポジトリを見てくれた人が好奇心のある方であれば、ソースコードを自分で読んでIssue等で使い方等の質問をしてきてくれるかもしれませんが、こういった人はとても稀です。多くの場合で、READMEの出来が悪ければブラウザバックの対象になるでしょう。
そのため、開発したソフトウェアに関する基本的なドキュメント、とりわけREADMEの整備が最も重要です。
READMEに書くべきこと
READMEに書くべき必要最低限の情報は次のとおりです。
- 公開したソフトウェアに関する簡単な要約文
- 公開したソフトウェアの仕様に関する簡単な要約文
- 公開したソフトウェアの導入方法
- 公開したソフトウェアを使用する場合の実装方法
公開したソフトウェアに関する簡単な要約文
まず、リポジトリを見た人がそのリポジトリにあるソフトウェアがどのような問題を解決するものなのかを知るための情報が必要でしょう。この項目はいわば広告のキャッチフレーズのようなもので、このソフトウェアの印象を表現した文言がいいでしょう。
また、この要約文はREADMEのヘッダー部分に近い場所にあることが好ましく、簡潔に一文で表現されるべきです。
具体的にどのようなものになるかというと、次のリンクにあるREADMEをご覧ください。
上記のREADMEのロゴ画像の直下にある以下の文言がこの項目に該当する要約文です。
公開したソフトウェアの仕様に関する簡単な要約文
次に書くべき項目は、このリポジトリで開発されているソフトウェアの主要な仕様に関する要約文です。この項目があることで、このリポジトリを見た開発者が実際にソースコードを見ることなく、ソフトウェアの仕様をおおまかに知ることができます。
この項目にはリポジトリで開発されているソフトウェアでどのような機能がサポートされているかを簡潔に書くべきです。他の開発者に伝えたい機能が複数ある場合は箇条書きで書くと良いでしょう。また、ソフトウェアの仕様をすべて書く必要はなく、特筆すべき仕様だけを厳選して書くようにしましょう。
例えば、以下リンクにあるFeaturesというセクションがこの項目の要約文にあたります。
公開したソフトウェアの導入方法
次に、他の開発者にとってこのソフトウェアを使用する際に知らなければいけないことは、このソフトウェアの導入方法です。考えてみれば当然のことで、仮に他の開発者がこのソフトウェアに興味を持ったとしても導入方法がわからなければ使われるわけがないですよね。
この項目は使用されるプラットフォームやフレームワーク等に応じて、初心者でも簡単に導入が可能なように記載されるべきです。ただ、なにからなにまでを記載する必要はなく、あくまでもソフトウェアを導入するための必要最低限のコマンド等を記載すると良いでしょう。
例えば、twitter_api_v2では以下リンクのセクションで、DartとFlutterごとのパッケージのインストール方法を記載しています。
また、必要に応じてシステム要件や動作要件などの情報も書くべきです。例えば、このソフトウェアが動作しないOSや、使用できないプログラミング言語やフレームワークのバージョン等があれば明記されるべきでしょう。
公開したソフトウェアを使用する場合の実装方法
公開されたOSSライブラリを使用してプログラムを書く開発者の立場から見ると、試しにコピペで動作するようなサンプルコードがあるかどうかで開発時の負担が大きく違ってきます。個人のOSS開発では詳細なリファレンスを用意することはなかなか難しいため、主要な機能をすぐに試せるスニペットがあれば使い方がわからず敬遠されるような自体は少なくなるでしょう。
この項目は公開するソフトウェアによって要否が分かれますが、もしこのソフトウェアがライブラリ等であればコピペで動作確認ができるサンプルコードを絶対に用意するようにしましょう。
例えば、twitter_api_v2では以下リンクのREADMEにサンプルコードを記載し、プロジェクト直下のexampleフォルダーに実際に動作するDartプログラムを用意しています。
さらにREADMEを魅力的にするために
READMEのヘッダーに表示するロゴ画像は必須ではありませんが、ロゴ画像があるのとないのとではREADMEの見栄えが大きく異なります。
画像にはテキストで表現できない多くの情報を持たせることができ、適切な画像を使用すればテキストを読むよりもより多くの情報を一瞬で伝えることができます。
例えば、twitter_api_v2の以下のロゴ画像を見ると、このライブラリがTwitterとTwitter API v2.0に関連するものであることが他のテキストを読まずとも一目で理解できます。
そのため、私個人の意見としてREADMEに表示するロゴ画像は、できれば用意したほうがいいです。また、ロゴ画像を使用する方法に加えて、リポジトリに関連する様々な指標を表示できるバッジを使用するといいでしょう。
ロゴ画像やバッジの作成方法についてはこの記事では割愛させていただくのですが、もし興味のある方はtwitter_api_v2のREADMEや、他の方が書かれた記事を参考にしてみてください。
ドキュメントが英語圏向けにローカライズされていない
もしかすると、「俺は日本人向けにしかドキュメントを書かない！」というワイルドな方もいるかもしれませんが、英語圏の方々が理解できるドキュメントを作れると圧倒的にソフトウェア開発のパイ食い競争で有利になれます。
なぜなら、名実ともにソフトウェア業界の中心は今も昔も米国であり、とりわけOSS開発が活発に行われている国が米国だからです。また、この記事を書いている時点で米国に次いでソフトウェア業界で大きな存在感を示しているのが中国とインドで、これらの国々のエンジニアは英語を卒なくこなせる方がとても多く、英語ドキュメントが存在することで米国以外の優秀な開発者も呼び込むことができます。
つまり、英語でドキュメントを作らないという行為は、最も巨大な市場を自ら捨てていることに等しいのです。また、英語でドキュメントを用意しないことによって、あなたが作ったソフトウェアが海外の影響力を持つエンジニアの目に留まることもないでしょう。
私は英語でドキュメントを作成することを強制はしませんが、もしあなたが作成したソフトウェアをより有名にしたいのであれば、絶対に英語ドキュメントを作成することをオススメします。
英語が苦手な方へ
しかし、そうは言っても英語が苦手という方はもちろんいるかと思います。
そういう方は恥ずかしがらず、DeepLといった文明の利器を使用しましょう。
私は学生時代から運良く英語圏の方々と交流できる機会を持てたので英語の読み書きは不自由なくできるのですが、それでも自分が書いた英文の表現が誤っていないかよく翻訳サイトを使用して英語から日本語に変換して確認しています。せっかくこうした便利なサービスがあるのに、活用しないのは本当にもったいないです。
もちろん、自分で英語の読み書きができることがベストですが、英語が苦手な方はこうしたサービスをどんどん使っていきましょう！
開発だけが行われ、適切な宣伝がされていない
次に、ドキュメント作成と併せてOSSの開発自体は順調に進んでいるものの、宣伝がされていないために閑散としているリポジトリを多く見かけます。
「良い製品であれば、勝手に顧客がつく」という考え方を持つ人もいるかもしれませんが、この考え方が通用するのは製品を開発している方が既にある程度有名で影響力があったり、名の通った大企業の場合のみです。
無名のOSS開発者が開発したソフトウェアがいかに優れていようと、それをただ作ってリポジトリに寝かせておくだけでは意味がありません。たまたま通りかかった有名人があなたの優秀なソフトウェアを発掘する可能性は万に一つもないのです。起こるかどうかもわからない可能性に賭けるよりも、自ら行動しましょう。
つまり、開発したソフトウェアの宣伝をして人々にこのソフトウェアの存在を知ってもらわなければいけないのです。
私が実践した宣伝
私はtwitter_api_v2を開発し始めた頃から宣伝を徹底的に行なっており、リリースのたびに様々なプラットフォームでこのライブラリの存在を知ってもらうために人々に呼びかけました。参考までに以下のサイトが私が宣伝を行った場所のリストです。
- Twitter（Dart/Flutterコミュニティ）
- Twitter Forum
- Discord
- Zenn
- Qiita
- Medium
ソースコードの質が低い
この項目はあまり優先度が高いものではありませんが、ソフトウェアを構成するソースコードの質も他の開発者が見る際に重要な要素になりえます。どれだけ優れたアルゴリズムを組み込んでいようと、ソースコードの質が低いと使用するのが不安になってしまいます。
また、ソースコードの質が低いと、外部から開発者を呼ぶ際に大きな障壁になるでしょう。すぐに意味の読み取れない変数名とメソッド名やスパゲッティコードを誰も見たくはないのです。
そのため、まずは当然ながらコーディングスキルを磨きましょう。いろいろな人が書いたソースコードや文献を読んだりして、コーディング時にすべきこととすべきではない一般的な考え方を学びましょう。
さらに、コーディングスキルに問題がなくなってきたら、コードの質を高く保ちながら持続可能な開発をするためにも、リポジトリの作成時に開発言語に応じた簡単な開発標準を作っておくことをオススメします。
私が開発するOSSライブラリでは、必ず以下リンクのようにSTYLEGUIDE.mdをプロジェクト直下に用意しておき、私自身を含めた全ての貢献者に対してこのルールに則ったコーディンをするように強制をしています。また、Dartのように静的解析ツールが提供されている場合は、このツールをPush時に必ず実行するようにGitHub Actionsのワークフローを設定しておくと良いでしょう。
テストコードが存在しない、または極端に少ない
最後に、OSSライブラリが敬遠される理由としてよく挙がるのが、テストコードが存在しないことやテストケースが極端に少ないことです。
自分だけで使うソフトウェアであればテストコードは不要かもしれませんが、他人に使ってもらおうと考えているのであればテストコードは必須です。テストコードがなければそのソフトウェアが安全に動作する保証はどこにもないですし、自分が作成するアプリケーションに本当に組み込んで良いものなのかどうか不安になります。
あなたの開発しているソフトウェアをたまたま見つけた開発者の方々を不安にさせないためにも、日頃からできる限り質の高いテストコードを書くようにしましょう。そして、GitHub ActionsなどのプラットフォームでCIを活用してテストを自動化し、全てのテストをパスしているかどうかを可視化するバッジをREADMEのヘッダー近くに表示しておくとより効果的です。
また、テスト結果のカバレッジレポートを解析して、GitHubで使えるバッジも作成できるサービスがありますので、参考までに紹介しておきます。
まとめ
ここまで偉そうに書いてきましたが、以上の事柄が私の経験を踏まえた、自分で開発したソフトウェアの名を売ろうとするすべてのOSS開発者が実践すべきことです。
もちろん、この記事に書いた方法を実践して必ず成功するわけではないですし、逆にこの記事の方法を試さずに成功するOSSも存在するでしょう。しかし、開発リポジトリの体裁を整えることと、開発だけではなく宣伝も積極的に行っていくことは、OSS開発をしていく上でとても重要な要素だと考えています。
この記事を読んでくれた方の中で、OSS開発で成功した方が出てくれればとても嬉しいです。
あと、あまり見た目重視というと叩かれそうですが、開発リポジトリの見た目はとても重要です。
貢献者の募集
twitter_api_v2はオープンソースですのでどのような方でも開発に貢献することができます。開発リポジトリの公用語は英語にしていますが、日本人の方々も大歓迎ですのでお気軽にIssueやPull Requestを作成してください。
また、このライブラリが役に立った場合にGitHub の開発リポジトリにスターを付けることや、Pub.dev でいいねを付けることもよろしくお願いします！これはtwitter_api_v2の開発コミュニティを活性化するためにとても大きな意味があります。
もしなにか疑問がある場合は開発リポジトリのディスカッションにでもスレッドを立ててください。
スポンサーの募集
私のオープンソース開発をサポートしてくださるスポンサーを募集しています。少額($1)からの寄付も可能ですので、以下のリンクから是非ご支援ください。
また、この記事にバッジを贈っていただくことでも支援は可能です。
Discussion