原文: How to Write a Good README File for Your GitHub Project
GitHub を初めて知った時、私 (原著者) はそれがどういうものか、何ができるのかわかっていませんでした。ここだけの話、それがコードの置き場所で、すべての開発者が持つべきものだと言われるがままにアカウントを作成しました。
初心者だった私は、長い間そのアカウントで何もしませんでした。しかしその後、テクノロジーに興味を持ち、他の開発者をフォローし、GitHub 上にある彼らの作品をチェックし始めました。そして、彼らには共通点があることに気がついたのです。彼らはみな素晴らしいプロジェクトをもち、オープンソースに貢献しているとともに、彼らのプロジェクトには詳細な README ファイルが含まれていました。
こうして README についての関心が高まり、私のプロジェクトにも試しにそれを追加することにしました。正直に言うと、私は作法もわからないまま焦ってそれを追加しました。はっきり言って、それは全く優れたものではありませんでした。ここで実物を見ることができます。
しばらくはそのままでした。しかし、実践と学習を続けることで、このように多少は優れたドキュメントに変えることができました。この改善により、プロジェクトへのエンゲージメントが高まり、他の開発者の参加が促進されました。
優れた README は、GitHub 上に作品を置いている大勢の開発者の中であなたを際立たせるのに役立つということも特筆すべき点です。
この記事では、README ファイルがどういうものかとその書き方を学びます。では最初に、README ファイルとは何かを理解しましょう。
README ファイルとは何か？
簡単に言うと、README ファイルは、あなたのプロジェクトの詳しい説明をユーザーに提供するガイドです。
また、README はプロジェクトの使用方法に関するガイドラインを含むドキュメントであるとも言えます。通常は、プロジェクトのインストールおよび実行方法についての説明が含まれます。
開発者として、README であなたのプロジェクトについてのドキュメントを提供する方法を知っておくことは不可欠です。その理由を以下に挙げます:
- README はプロジェクトに出会った人が最初に目にするファイルなので、ある程度簡潔に、とはいえ詳細なものにする必要があります。
- 他の数多くのプロジェクトから、あなたのプロジェクトを際立たせてくれます。もちろん、プロジェクト自体も優れたものであることが重要です。
- プロジェクトが何をどのように提供する必要があるか、あなた自身が考えを集中させるのに役立ちます。
- 文書作成スキルを向上させます。フリードリヒ・ニーチェの格言によれば:
A good writer possesses not only his own spirit but also the spirit of his friends.
(訳: 優れた作家とは、彼自身の精神のみならず、仲間の精神もまた持ち合わせているものである)
プロジェクトに取り組む際、他の開発者にあなたのコードとその機能を理解してもらう必要があることを忘れないようにしましょう。そのために、コードとは別にガイドを添付しておくことが役に立ちます。
例えば、先ほどシェアした私の最初のプロジェクトの例には、優れた README がありません。そのため、プロジェクトが素晴らしい物だったとしても、リポジトリをクローンした後どうすれば良いのか初心者にとって理解しづらいものになっています。実はコンピューターウイルスである可能性すらあるかもしれません。
このような GitHub のプロジェクトでは、それがどんなに素晴らしいものであったとしても、優れた README がなければ、他の開発者は取り組んだり理解しようとはしないでしょう。
では、このプロジェクトを見てみましょう。ここでは、プロジェクトが何を行い、何を必要とするか、またプロジェクトを使用する場合やプロジェクトに貢献したい場合にどうやって始めたら良いかがわかります。
このように、うまく書かれた README は強力であり、プロジェクトを変えることができます。
それでは、優れた README の書き方に入りましょう。
優れた README の書き方 – 段階的なガイド
まず重要なことは、優れた README を作成する唯一の正しい方法というものはありません。ですが大きな誤りが一つあります。それは、README を全く含まないことです。
さまざまな README ファイルの研究と調査を行った結果、私が見つけたベストプラクティスがあります。それこそが私がシェアすることです。そして、私はいつも自分にこう言い聞かせています:
Every day is a learning day.
(訳: 日々精進)
つまり、あなたがキャリアを積む中で進歩し成長するにつれて、優れた README を作るものは何か、またどう改善するかについて、独自の考えを持つようになることでしょう。あなただけのユニークなガイドを思いつくかもしれません。
具体的な書き方に入る前に、もう一点、プロジェクトの README を書く際はプロジェクトに関する What、Why、How がわかるようにすることが重要です。
以下のような質問に沿って考えると書きやすいでしょう:
- 何が動機だったのか？
- なぜこのプロジェクトを構築したのか？
- このプロジェクトが解決する課題は何か？
- 何を学んだのか？
- このプロジェクトの優れた点は何か？
プロジェクトに多くの機能がある場合は、「機能」セクションを追加して一覧を載せることを検討しましょう。
README に含めるもの
1. プロジェクトのタイトル
プロジェクトの名前です。1 文でプロジェクト全体を説明し、プロジェクトの主な目的や狙いが何か (What) を、人々に理解してもらいやすくします。
2. プロジェクトの説明
これは、多くの新米開発者が見落としてしまいがちな、プロジェクトの重要な構成要素です。
プロジェクトの説明は極めて重要な部分です。よく練られた説明は、他の開発者だけでなく、将来あなたの雇い主になる可能性のある人々にも、あなたの作品の魅力を伝えることができます。
README の説明の品質が、優れたプロジェクトか否かの差を付けることがよくあります。優れたプロジェクトは、以下のような内容を説明、紹介する場として README を活用します:
- アプリケーションが何をするか、
- 使用した技術についてなぜそれを採用したか、
- 直面した困難について、また将来実装したいと考えている機能について。
3. 目次 (任意)
README がとても長い場合は、異なるセクションへ移動しやすくするために目次を追加することをお勧めします。そうすることで、読者がプロジェクト内を探索しやすくなります。
4. プロジェクトのインストールおよび実行方法
ユーザーがインストールしたり、「POS (販売時点情報管理)」のようなマシン上でローカル実行する必要があるプロジェクトに取り組んでいる場合は、プロジェクトのインストールに必要な手順と、もしあれば必要な依存関係も追加すべきです。
開発環境を設定して実行する方法の段階的な説明を提供するようにしてください。
5. プロジェクトの使用方法
ユーザー／コントリビューターがプロジェクトを使用できるように、手順や例を提供しましょう。そうすることで、問題に直面した場合にも対処しやすくなります。何をすべきか分からない時は常にここを参照すれば良いからです。
また、実行中のプロジェクトの例や、プロジェクト内で使用されている構造や設計方針を示すために、スクリーンショットなどの資料を追加して視覚的な補助資料として活用できます。
さらに、プロジェクトでパスワードまたはユーザー名などの認証が必要な場合には、このセクションに認証情報を含めるとよいでしょう。
6. クレジットを入れる
チームまたは組織としてプロジェクトに取り組んだ場合は、共同制作者／チームメンバーの一覧を載せるようにしましょう。その人たちの GitHub プロフィールやソーシャルメディアへのリンクも添えておくとよいでしょう。
また、プロジェクトの構築にあたってチュートリアルを参考にしたり、特定の資料を参照しており、それがユーザーにも役立つ可能性がある場合、それらへのリンクもここに含めるようにしましょう。
これは、あなたの感謝の気持ちを表明し、他の人がプロジェクトのコピーを直接入手しやすくする一つの方法です。
7. ライセンスの付与
ほとんどの README ファイルにおいて、ライセンスは最後の部分に置かれることが多いです。これは、他の開発者にプロジェクトを用いてできることとできないことを知らせるためのものです。
取り組んでいるプロジェクトの種類によって、さまざまなタイプのライセンスがあります。選んだライセンスがプロジェクトの得る貢献を決定します。
最も一般的なライセンスは GPL ライセンスで、これはコードを改変し、商用目的で利用することを他の人に許可します。ライセンスを選ぶ際に助けが必要な場合は、次のリンクをチェックしてください: https://choosealicense.com/
ここまで説明してきたことは、優れた README の最小要件です。では、以下のセクションを追加して、さらに人目を引きインタラクティブにすることも検討してみてください。
追加の README セクション
8. バッジ
バッジは必須ではありませんが、他の開発者にあなたが何を行っているかを伝えるシンプルな方法です。
このセクションを用意することで、重要なツールへリンクしやすくしたり、フォーク、コントリビューター、および未解決の問題の数などのような、プロジェクトのシンプルなステータスを表示するのに役に立ちます。
以下はバッジの活用方法の参考として、私のプロジェクトのスクリーンショットです:
このセクションの良い点は、自動的に更新されることです。
ではどこで入手すればいいでしょうか？ shields.io がホストしているバッジをチェックしてみてください。たくさんのバッジが用意されています。今は、何を表しているか全部は理解できないかもしれませんが、やがてわかるようになるでしょう。
9. プロジェクトに貢献する方法
これは、他の開発者に貢献してもらう必要があるオープンソースプロジェクトを開発している場合、最も役に立つものです。プロジェクトに貢献する方法を彼らに伝えるためのガイドラインを追加するとよいでしょう。
また、後の衝突を避けるためには、オープンソースプロジェクトのために適切なライセンスを選ぶことが重要です。コントリビューションガイドラインを追加することも、重要な役割を果たしてくれるでしょう。
最も一般的なガイドラインには、コントリビューター行動規範と貢献ガイドが含まれています。これらのドキュメントは、プロジェクトのためのルールを設定する際に、必要な支援を提供してくれます。
10. テストを追加する
もうひと頑張りして、アプリケーション用のテストを作成してみましょう。また、コード例と実行方法を備えるようにしてください。
これはプロジェクトが問題なく動作することをあなたが確信しており、信頼できるということを表すのに役に立ち、他の人々にも信頼を与えることができます。
補足事項
README を記述する際に注意する補足事項を以下にいくつか挙げます:
- 最新の状態を保つ - 必ず、ファイルを常に最新の状態にしておくことをお勧めします。変更がある場合は、必要に応じてファイルを更新してください。
- 言語を選択する - 私たちはさまざまな地域で生まれ育ち、異なる言語を話します。ですが、それはコードを自国語に翻訳する必要があることを意味してはいません。英語はグローバルに通用する言語であるため、英語で記述された README は機能してくれます。ターゲット層が英語に慣れていない場合は、翻訳ツールの使用も検討してください。
まとめ
これで、README ファイルを改善したり、初めての README ファイルを書き始めるために必要なすべてが揃いました。
あなたは次の、もしくは既存のプロジェクトにもインタラクティブで参考になるガイドを追加して、プロジェクトを際立たせることができるでしょう。
プロジェクトの README を自動的に生成できるツールも多数ありますが、自動化に移行する前に、まずは自分でやってみることが良い方法です。ツールをチェックしたい場合は、次のようなものがあります:
ここまでお読みくださいましてどうもありがとうございました。もしも記事を楽しんでいただき、それが役に立ったならば、他の開発者が彼らのプロジェクトを改善できるように記事をシェアしてください。
あなたが新しく作り上げた README ファイルを見ることができれば幸いです。以下のリンクのいずれかを通じてシェアしてください。
Twitter | YouTube | LinkedIn | GitHub でつながりましょう。
貴重なご意見をお聞かせください。率直なフィードバックをお待ちしております！
エンジョイコーディング ❤