こんにちは。現役エンジニアの”はやぶさ”@Cpp_Learningです。
仕事でもプライベートでもREADME.mdを書く機会が多いので、あまり雑なREADME.mdを書かないように自作のテンプレート使うようになりました。（テンプレートを使うことで時短にもなる）
本記事では『シンプルなREADME.mdの書き方』と『コピペで使える”README”テンプレート』を紹介します。
ご参考になると嬉しいです。
本記事を参考にオリジナルのREADME.mdを作成するのが良いと思います
Contents
READMEとは
GitHubユーザーにはお馴染みの”README”ですが、Wikipediaでは以下のように説明しています。
リードミー（Readme）とは、ソフトウェアを配布する際の添付文書のひとつ。配布物の一般的な情報を記載したファイルである。多くの場合、そのソフトウェアをインストールし使用する前に読むべきものとされている。
引用元：Wikipedia
”README”については、他にも色々な説明がありますが、私なりの言葉で表現すると…
『まず最初に読んでほしいドキュメント』
と考えています。この「最初に読んでほしい」という部分が人によって異なるため「この書き方が正解！」というのも人によって異なると感じています。
例えば、Chainer｜GitHubの”README”は以下の通りです。
顔であるロゴから始まり、Chainerが「深層学習フレームワーク」であることを明示したあと、「詳細説明のあるリンク」と「Chainerの簡潔な説明」が記述してあります。
シンプルなREADMEが好き
繰り返しますが、”README”は『まず最初に読んでほしいドキュメント』だと考えています。
そして、「最初に読んでほしい」という部分が人によって異なるため、「READMEの内容に過不足があるなぁ」と感じるのは、しょうがないことだと考えています。
ただ、せっかくなら『最初に読んでくれたら、良いことあるよ！』という想いが伝わる”README”を書きたいですよね(*･ω･)ﾉ♪
個人的にはシンプルな”README”が好きです。
あなたの好きな”README”はどんな記述ですか？考えてみてね
READMEのテンプレート
私が使っている自作の”README”テンプレートが以下です。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 |
# Name（リポジトリ/プロジェクト/OSSなどの名前） 分かりやすくてカッコイイ名前をつける（今回は"hoge"という名前をつける） "hoge"が何かを簡潔に紹介する # DEMO "hoge"の魅力が直感的に伝えわるデモ動画や図解を載せる # Features "hoge"のセールスポイントや差別化などを説明する # Requirement "hoge"を動かすのに必要なライブラリなどを列挙する * huga 3.5.2 * hogehuga 1.0.2 # Installation Requirementで列挙したライブラリなどのインストール方法を説明する ```bash pip install huga_package ``` # Usage DEMOの実行方法など、"hoge"の基本的な使い方を説明する ```bash git clone https://github.com/hoge/~ cd examples python demo.py ``` # Note 注意点などがあれば書く # Author 作成情報を列挙する * 作成者 * 所属 * E-mail # License ライセンスを明示する "hoge" is under [MIT license](https://en.wikipedia.org/wiki/MIT_License). 社内向けなら社外秘であることを明示してる "hoge" is Confidential. |
このテンプレートをコピペして、必要に応じて改良しています。
もし、このテンプレートをGitHubで公開したり、Markdownプレビュー機能のあるエディタで閲覧した場合のイメージは、以下から確認できます。
このテンプレートは自由に使ってOKです！
【実践】README.mdの書き方
テンプレートの使用例を紹介します。
『Pythonで物理シミュレーションをしよう！』シリーズの”README”を書いたので、良ければ参考にして下さい。
『Physics_Sim_Py』のREADME
『Pythonで物理シミュレーションをしよう！』シリーズの概要は以下の通りです。
Python向けレトロゲームエンジンのpyxelを使い「物理シミュレーションの作り方」を楽しむ学べるチュートリアル集
テンプレートをベースに作成した”README”が以下です。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 |
# Physics_Sim_Py "Physics_Sim_Py" is a tutorial of physics simulations with Python. # DEMO You can learn how to making cute physics simulations (looks retro game).  This animation is a "Cat playing on trampoline"! You can get basic skills for making physics simulations. # Features Physics_Sim_Py used [pyxel](https://github.com/kitao/pyxel) only. ```python import pyxel ``` [Pyxel](https://github.com/kitao/pyxel) is a retro game engine for Python. You can feel free to enjoy making pixel art style physics simulations. # Requirement * Python 3.6.5 * pyxel 1.0.2 Environments under [Anaconda for Windows](https://www.anaconda.com/distribution/) is tested. ```bash conda create -n pyxel pip python=3.6 Anaconda activate pyxel ``` # Installation Install Pyxel with pip command. ```bash pip install pyxel ``` # Usage Please create python code named "demo.py". And copy & paste [Day4 tutorial code](https://cpp-learning.com/pyxel_physical_sim4/). Run "demo.py" ```bash python demo.py ``` # Note I don't test environments under Linux and Mac. # Author * Hayabusa * R&D Center * Twitter : https://twitter.com/Cpp_Learning # License "Physics_Sim_Py" is under [MIT license](https://en.wikipedia.org/wiki/MIT_License). Enjoy making cute physics simulations! Thank you! |
これのイメージも以下から確認できます。
以降で書き方のポイント（私がどんなことを考えながら作成したか）を説明します。
README作成のコンセプトとポイント
”README”の作成コンセプトですが、私の場合は…
『このリポジトリは何？どんなことができる？』に対するアンサーのつもりで書いています。
より具体的には以下のポイントを考えながら、”README”を作成しています。
- 基本は英語
- 分かりやすくてカッコイイ名前を付ける
- 冒頭でインパクトのあるデモ（本リポジトリを直感的に理解させる）
- 各説明はできる限り簡潔に書く（数行で書けると良い）
- 基本的な使い方までガイドする
- 詳細な説明はリンクで別サイトにジャンプ
- 連絡先やライセンスが明示してあると安心
- 過去・未来の自分が読んでも理解できるように書く
GitHub用のREADMEの場合、世界中の人が閲覧するため、基本的には英語で書くのが良いと考えています。ただし、社内向けなど読み手が日本人しかいない場合は、日本語で書くのも親切かもしれません。
名前については「カッコイイ」・「可愛い」・「親しみやすい」などの想いを込めて名付けると愛着が沸くし、他人からも魅力的に見えます。
また、『このリポジトリは何？どんなことができる？』が直感的に理解できるインパクトのあるデモを冒頭で紹介したあと、各説明を簡潔に記述して終了です（数行で説明できるとGood!）
もし詳細な説明が必要な場合は、リンクを張って別サイトを参照してもらいます。
最後に、ライセンスや連絡先があると読み手が安心して使ってくれる気がするので、載せてます。
以下の文は蛇足だけど…まぁ遊び心があって良いかと(*･ω･)ﾉ♪
Enjoy making cute physics simulations!
Thank you!
あとは”README”に限らず、あらゆるドキュメントを作成する上で、私が気を付けているポイントが以下の通りです。
過去・未来の自分が読んでも理解できるように書く
まとめ
本記事では『シンプルなREADME.mdの書き方』や『コピペで使える”README”テンプレート』を紹介しました。
今回紹介したテンプレートは自由に使ってOKです！もちろんカスタムも大歓迎なので、自分好みの『オリジナル”README”テンプレート』の作成に挑戦してみてくださいな。
ちなみに”README.md”を作成するときのエディタにはVSCodeを愛用しています。
色々書きましたが、少しでも参考になる箇所があると嬉しいです。
最後に愛用の仕事道具を紹介します。
