Help us understand the problem. What is going on with this article?

githubで使えるイカしたREADMEの作り方

概要

散らかっていたgithubを整理して、きっちりしたREADMEを書いたので、その方法をまとめました。
一度フォーマットを決めておけば後々楽になるので、ぜひこれを読んでイケてるREADMEを作成してみてください。

READMEの構成

色々と調べた結果、このような基礎構成になりました。

# name

image or gif

## Overview

## Requirement

## Usage

## Features

## Reference

## Author

[twitter](https://twitter.com/Kotabrog)

## Licence

[MIT](https://......)

必要があれば、これに付け加えていく感じです。
私のgithubになりますが、例えばこんな感じになります。

https://github.com/kotabrog/ft_mini_ls

以下ではそれぞれについて簡単に解説をいたします。

name

私は基本的にrepository nameを書いています。

image or gif

やっぱり最初にイメージがあるとインパクトがありますからね。差し込み方はこんな感じです。

![gif](https://github.com/kotabrog/ft_mini_ls/blob/main/image/ft_mini_ls.gif)

Overview

ここには概要を書いています。基本的に1~2行くらいに収まるようにします。

Requirement

環境や、必要なライブラリなどについて言及しています。
……とはいっても、場合によっては動作確認をした環境だけ載せているという感じで、必ずしも必要としてない条件も載せてしまっています。
例えば以下のように示しています。
必要があればバージョンなども載せています。

- macOS
- clang
- Docker 19.03.6

Usage

簡単な使い方です。

Features

詳しい仕様について、基本的に箇条書きで紹介しています。
Usageで紹介しなかった詳しい使い方も書いています。
箇条書きで書きづらい場合や、長くなりそうな場合には、「Features」ではなく「Description」に変更したほうが個人的にはピンときます。

Reference

参考URLを書きます。

Author

自分の情報を載せています。
私はTwitterのアカウントなんかを載っけています。

Licence

Licenceについて載せています。例えば以下のような感じです。

[MIT](https://......)

Licenceについて

Licence、何それ、おいしいの?と思っていたのですが、READMEを作るために調べていたら以下のよう言葉を見かけました。

著作権を主張しないつもりなんだったらそれを明示的に宣言して欲しい。ライセンスが明示されていないのは、どんなライセンスよりも厳しいライセンスだ。

Ruby 1.9.2リリースとWEBrick脆弱性問題の顛末より)

たしかに、明記されていないと著者の意向がわからないですものね。

せっかくプログラムをgithubに載せたのなら、色々な人に使ってもらいたいし、できれば著者へのリンクをつけていただいたり、紹介していただきたい……と思ったので、私はできるだけ制限のないライセンスである「非コピーレフト型」の「MIT」を選択しました。
Licenceについて詳しくは以下の参考URLをご参照ください。

gifについて

ページの最初に画像があるとインパクトがありますが、それが動いていたらなおのことインパクトがあります。
しかし、gif画像なんて作ったことない……という方に、簡単に作れるサイトをご紹介します。

LICEcapはディスプレイに写っているものを簡単にgif画像にすることができるアプリです。
BannerKoubouは、gif画像を編集することができるWebサイトです。

使い方としては、最初にLICEcapでディスプレイに表示しているものをgif画像にして、その後で、前後の部分やもたついている部分をBannerKoubouで切り取るといい感じのgif画像を簡単に作ることができます。

ぜひお試しください!

Markdownについて

READMEで使えるMarkdownのチートシートは、以下のものがわかりやすかったです。

また、READMEの書き方についても参考にさせて頂いたこちらの記事では、htmlやcssの書き方を利用した画像の貼り方も紹介しているので、ぜひ御覧ください。

おわりに

プログラムを書くことが忙しくて、READMEなどはおろそかにしてしまいがちですが、この投稿がそんな忙しいエンジニアの手助けになれたら嬉しいです。
(いっぱい調べたので、見てほしい)。

参考URL

Kotabrog
AIと友達になりたい人。 機械学習エンジニアです。
https://kotabrog.com/
Why not register and get more from Qiita?
  1. We will deliver articles that match you
    By following users and tags, you can catch up information on technical fields that you are interested in as a whole
  2. you can read useful information later efficiently
    By "stocking" the articles you like, you can search right away