プログラミング PR

【GitHub】シンプルなREADME.mdの書き方 -コピペで使えるテンプレート付き-

READMEの書き方
記事内に商品プロモーションを含む場合があります

こんにちは。現役エンジニアの”はやぶさ”@Cpp_Learningです。

仕事でもプライベートでもREADME.mdを書く機会が多いので、あまり雑なREADME.mdを書かないように自作のテンプレート使うようになりました。(テンプレートを使うことで時短にもなる)

本記事では『シンプルなREADME.mdの書き方』『コピペで使える”README”テンプレート』を紹介します。

ご参考になると嬉しいです。

本記事を参考にオリジナルのREADME.mdを作成するのが良いと思います

READMEとは

GitHubユーザーにはお馴染みの”README”ですが、Wikipediaでは以下のように説明しています。

リードミー(Readme)とは、ソフトウェアを配布する際の添付文書のひとつ。配布物の一般的な情報を記載したファイルである。多くの場合、そのソフトウェアをインストールし使用する前に読むべきものとされている。

引用元:Wikipedia

”README”については、他にも色々な説明がありますが、私なりの言葉で表現すると…

『まず最初に読んでほしいドキュメント』

と考えています。この「最初に読んでほしい」という部分が人によって異なるため「この書き方が正解!」というのも人によって異なると感じています。

例えば、Chainer|GitHubの”README”は以下の通りです。

Chainer README顔であるロゴから始まり、Chainerが「深層学習フレームワーク」であることを明示したあと、「詳細説明のあるリンク」と「Chainerの簡潔な説明」が記述してあります。

シンプルなREADMEが好き

繰り返しますが、”README”はまず最初に読んでほしいドキュメントだと考えています。

そして、「最初に読んでほしい」という部分が人によって異なるため、「READMEの内容に過不足があるなぁ」と感じるのは、しょうがないことだと考えています。

ただ、せっかくなら『最初に読んでくれたら、良いことあるよ!』という想いが伝わる”README”を書きたいですよね(*・ω・)ノ♪

個人的にはシンプルな”README”が好きです。

あなたの好きな”README”はどんな記述ですか?考えてみてね

スポンサーリンク

READMEのテンプレート

私が使っている自作の”README”テンプレートが以下です。

このテンプレートをコピペして、必要に応じて改良しています。

もし、このテンプレートをGitHubで公開したり、Markdownプレビュー機能のあるエディタで閲覧した場合のイメージは、以下から確認できます。

README_Template

このテンプレートは自由に使ってOKです!

【実践】README.mdの書き方

テンプレートの使用例を紹介します。

Pythonで物理シミュレーションをしよう!』シリーズの”README”を書いたので、良ければ参考にして下さい。

『Physics_Sim_Py』のREADME

『Pythonで物理シミュレーションをしよう!』シリーズの概要は以下の通りです。

概要

Python向けレトロゲームエンジンのpyxelを使い「物理シミュレーションの作り方」を楽しむ学べるチュートリアル集

テンプレートをベースに作成した”README”が以下です。

これのイメージも以下から確認できます。

README_Pyhsics_Sim_Py

以降で書き方のポイント(私がどんなことを考えながら作成したか)を説明します。

README作成のコンセプトとポイント

”README”の作成コンセプトですが、私の場合は…

『このリポジトリは何?どんなことができる?』に対するアンサーのつもりで書いています。

より具体的には以下のポイントを考えながら、”README”を作成しています。

  • 基本は英語
  • 分かりやすくてカッコイイ名前を付ける
  • 冒頭でインパクトのあるデモ(本リポジトリを直感的に理解させる)
  • 各説明はできる限り簡潔に書く(数行で書けると良い)
  • 基本的な使い方までガイドする
  • 詳細な説明はリンクで別サイトにジャンプ
  • 連絡先やライセンスが明示してあると安心
  • 過去・未来の自分が読んでも理解できるように書く

GitHub用のREADMEの場合、世界中の人が閲覧するため、基本的には英語で書くのが良いと考えています。ただし、社内向けなど読み手が日本人しかいない場合は、日本語で書くのも親切かもしれません。

名前については「カッコイイ」・「可愛い」・「親しみやすい」などの想いを込めて名付けると愛着が沸くし、他人からも魅力的に見えます。

また、『このリポジトリは何?どんなことができる?』直感的に理解できるインパクトのあるデモを冒頭で紹介したあと、各説明を簡潔に記述して終了です(数行で説明できるとGood!)

もし詳細な説明が必要な場合は、リンクを張って別サイトを参照してもらいます。

最後に、ライセンスや連絡先があると読み手が安心して使ってくれる気がするので、載せてます。

以下の文は蛇足だけど…まぁ遊び心があって良いかと(*・ω・)ノ♪

Enjoy making cute physics simulations!

Thank you!

あとは”README”に限らず、あらゆるドキュメントを作成する上で、私が気を付けているポイントが以下の通りです。

過去・未来の自分が読んでも理解できるように書く

まとめ

本記事では『シンプルなREADME.mdの書き方』『コピペで使える”README”テンプレート』を紹介しました。

今回紹介したテンプレートは自由に使ってOKです!もちろんカスタムも大歓迎なので、自分好みの『オリジナル”README”テンプレート』の作成に挑戦してみてくださいな。

ちなみに”README.md”を作成するときのエディタにはVSCodeを愛用しています。

Visual Studio Code でMarkdown
【仕事効率化】Visual Studio Code で Markdown を使いこなす【仕事効率化】Visual Studio Code(VSCode) で Markdown を使い自分用のメモやチートシート・Tips集などのドキュメント作成をキーボード1つで効率的に実施しよう!...

色々書きましたが、少しでも参考になる箇所があると嬉しいです。

はやぶさ
はやぶさ
理系応援ブロガー”はやぶさ”@Cpp_Learningは頑張る理系を応援します!

最後に愛用の仕事道具を紹介します。

PICK UP BOOKS

  • 数理モデル入門
    数理モデル
  • Jetoson Nano 超入門
    Jetoson Nano
  • 図解速習DEEP LEARNING
    DEEP LEARNING
  • Pythonによる因果分析
    Python