READMEを書こう
2020年06月20日
自己紹介
名前: 三宅 英明
Twitter: @mollifier
神戸のプログラマ
シェルスクリプト
シェルスクリプト
「新しいLinuxの教科書」を読むと、かっこいいシ
ェルスクリプトが作れるようになります
シェルスクリプト
みなさんにもぜひ挑戦してほしい
出来上がったらみんなに公開してほしい
シェルスクリプト
公開
シェルスクリプト
公開するときにつきものなのがREADMEファイ
ル
READMEとは
READMEとは
アプリケーションやコマンドラインツールにだいた
い付いているやつです
READMEとは
READMEとは
READMEとは
アプリケーションの使い方や注意点などを書い
た文章
READMEとは
何か自分でツールを作ったとします
READMEとは
それだけではどうやって使えばよいか分からない
READMEとは
公開しても誰も使ってくれない
READMEとは
というか、自分でも使い方を忘れてよく分からな
くなる
READMEとは
READMEがちゃんとしていたら本格的な感じが
出てくる
READMEとは
でもいざ書こうとしてみると、意外と難しい
READMEとは
というわけで、今日はREADMEの書き方につい
てお話します
READMEの目的
READMEの目的
何のためにREADMEを書くのか
READMEの目的
目的1
そのアプリケーションを初めてみた人が、
READMEを読んでそれを使うかどうかを判断す
る
READMEの目的
目的2
アプリケーションを使い始めた人が、README
を読んで使い方を知る
READMEの目的
まだインストールしていない人か、使い始めた人
向けに書く
READMEに何を書くか
READMEに何を書くか
まだインストールしていない人か、使い始めた人
向けに書く
READMEに何を書くか
そう考えると、だいたい書くことは決まってくる
READMEに何を書くか
典型的な例
Name
Description
READMEに何を書くか
典型的な例
Install
Usage
Option
Configuration
READMEに何を書くか
Name
名前
READMEに何を書くか
Name
もちろん必要
かっこいい名前にしよう
READMEに何を書くか
Description
1、2行の簡単な説明
READMEに何を書くか
Description
それが何なのか説明がないと意味がわからない
READMEの最初の方に書く
READMEに何を書くか
説明が難しいなら、画像が有効
READMEに何を書くか
DEMOとして書いてあることがある
使ってる様子の紹介、スクリーンショットなど
こういうのを足すのもあり
READMEに何を書くか
Install
インストール、初期設定の方法
READMEに何を書くか
Install
最初の手順が分からないと使えない
READMEに何を書くか
Install
1行のコマンドでインストールできるのが理想
READMEに何を書くか
1行で無理なら必要なコマンドを全部書く
$ git clone https://github.com/tool.git
~/tool
$ cd ~/tool
$ ./setup.sh
READMEに何を書くか
単純にコピペで実行できるように
READMEを読む人は何も分かってないことに気
をつけよう
READMEに何を書くか
Usage
使用方法、起動方法
READMEに何を書くか
Usage
一番大事
「こうやって実行したら、こうなる」という形で書く
READMEに何を書くか
例
$ bookmark add
現在のディレクトリをブックマークに追加します
READMEに何を書くか
Usage
説明が難しかったら、例を書くのも良い
READMEに何を書くか
# ~/workをブックマークに追加する
$ bookmark add work ~/work
$ cd ~/tmp
# workという名前で~/workに移動できる
$ bookmark cd work
READMEに何を書くか
Option
オプションの説明
READMEに何を書くか
Option
オプションがあるなら書く
(当たり前ですが)書かないと分からない
READMEに何を書くか
Option
これも、説明が難しかったら例を書くのも有効
READMEに何を書くか
Configuration
設定方法
READMEに何を書くか
Configuration
環境変数、設定ファイルなどで設定を変更できる
なら、その説明を書く
READMEに何を書くか
典型的な例
Description (名前)
Description (簡単な説明)
READMEに何を書くか
典型的な例
Install (インストール)
Usage (使用方法)
Option (オプション)
Configuration (設定方法)
READMEに何を書くか
内部の詳細とかは書かなくてもよい
READMEに何を書くか
ユーザーはそんなこと気にしない
そこまで読んでくれない
READMEに何を書くか
外から見た動作を書けばOK
READMEを書く時のコツ
READMEを書く時のコツ
自分でコマンドラインツールとかを作ってるとき
READMEを書く時のコツ
だいたい、実装してるときが盛り上がりのピーク
READMEを書く時のコツ
完成すると達成感がある
READMEを書く時のコツ
そのあとREADMEを書こうとしても、だいたいや
る気が出ない
地味すぎる
READMEを書く時のコツ
READMEは本体を実装する前に書くのがよい
READMEを書く時のコツ
実装する前に、このツールで何をしたいのかを決
めて、それを書く
READMEを書く時のコツ
先に外から見た動作をREADMEに書いて、そう
なるように内部を実装する
ちょっとした仕様書としても使える
READMEを書く時のコツ
実装する前なので、最初に使うユーザーと同じ
気持ちで書ける
READMEを書く時のコツ
実装していくうちに詳しくなって、ユーザーの気
持ちを忘れてしまう
READMEを書く時のコツ
「こういうふうに作りました」ではなく「こういうふ
うになっていてほしい」「こういう使い方をした
い」というユーザー目線で仕様を決めてそれを
書く
READMEを書く時のコツ
そうやって仕様を決めると使いやすくなるはず
READMEを書く時のコツ
というわけで、先に書くのをおすすめします
まとめ
まとめ
READMEは大事
まとめ
めんどくさいので雑になりがち
まとめ
初めのうちは他の人が作ったツールとかを参考
にするのがよい
まとめ
慣れてくると大体パターンが決まってくる
まとめ
なので、世の中にあるいろんなアプリケーション
とかツールとかを使ってみるのが大事
まとめ
盛り上がってきたらぜひ自分でもぜひコマンドラ
インツールを作ってみてください
まとめ
そのときは、この発表とか「新しいLinuxの教科
書」とかも参考になると思います
まとめ
ありがとうございました

More Related Content

PDF
プロのためのNode-RED再入門
PDF
Protocol Buffers 入門
PPTX
Polyphony の行く末(2018/3/3)
PDF
pixivのインフラを支える技術
PDF
【Unite 2018 Tokyo】60fpsのその先へ!スマホの物量限界に挑んだSTG「アカとブルー」の開発設計
PDF
Unityのサウンド状況を調べまくって分かったアレコレ
PPTX
ハードウェア技術の動向 2015/02/02
PDF
Deep Dive async/await in Unity with UniTask(UniRx.Async)
プロのためのNode-RED再入門
Protocol Buffers 入門
Polyphony の行く末(2018/3/3)
pixivのインフラを支える技術
【Unite 2018 Tokyo】60fpsのその先へ!スマホの物量限界に挑んだSTG「アカとブルー」の開発設計
Unityのサウンド状況を調べまくって分かったアレコレ
ハードウェア技術の動向 2015/02/02
Deep Dive async/await in Unity with UniTask(UniRx.Async)

What's hot (20)

PDF
Design for Understanding:理解のデザインとしての情報アーキテクチャ
PDF
サムライスピリッツキャラクター制作事例 キャラクターモデル編
 
PDF
いまさら聞けないarmを使ったNEONの基礎と活用事例
PDF
ARM CPUにおけるSIMDを用いた高速計算入門
PDF
脆弱性スキャナVuls(入門編)
PDF
Audio QueueでSin波再生
PDF
【Unity道場スペシャル 2017博多】TextMesh Pro を使いこなす
PDF
PHPからJavaへ乗り換えた。そんな昔話をしよう
PDF
DSIRNLP #3 LZ4 の速さの秘密に迫ってみる
PDF
ROS2のリアルタイム化に挑む WG初参加
PDF
【Unite Tokyo 2019】SRPで一から描画フローを作ってみた! ~Unity描画フローからの脱却~
PPTX
ゼロから始める自作 CPU 入門
PDF
世界最強のソフトウェアアーキテクト
PPTX
CEDEC2021 ダウンロード時間を大幅減!~大量のアセットをさばく高速な実装と運用事例の共有~
PDF
『アナザーエデン 時空を超える猫』スマートフォンでのRPG体験の実現のためにしてきたこと
PPTX
OpenVRやOpenXRの基本的なことを調べてみた
PDF
スクリプトエンジン作って 無双する
PDF
HTML5 + JavaScriptでDRMつきMPEG-DASHを再生させる
PDF
TDPT + VMCプロトコル on WebRTC
PDF
Goでかんたんソースコードの静的解析
Design for Understanding:理解のデザインとしての情報アーキテクチャ
サムライスピリッツキャラクター制作事例 キャラクターモデル編
 
いまさら聞けないarmを使ったNEONの基礎と活用事例
ARM CPUにおけるSIMDを用いた高速計算入門
脆弱性スキャナVuls(入門編)
Audio QueueでSin波再生
【Unity道場スペシャル 2017博多】TextMesh Pro を使いこなす
PHPからJavaへ乗り換えた。そんな昔話をしよう
DSIRNLP #3 LZ4 の速さの秘密に迫ってみる
ROS2のリアルタイム化に挑む WG初参加
【Unite Tokyo 2019】SRPで一から描画フローを作ってみた! ~Unity描画フローからの脱却~
ゼロから始める自作 CPU 入門
世界最強のソフトウェアアーキテクト
CEDEC2021 ダウンロード時間を大幅減!~大量のアセットをさばく高速な実装と運用事例の共有~
『アナザーエデン 時空を超える猫』スマートフォンでのRPG体験の実現のためにしてきたこと
OpenVRやOpenXRの基本的なことを調べてみた
スクリプトエンジン作って 無双する
HTML5 + JavaScriptでDRMつきMPEG-DASHを再生させる
TDPT + VMCプロトコル on WebRTC
Goでかんたんソースコードの静的解析
Ad

Recently uploaded (11)

PDF
ココロ分解帳|感情をやさしく分解し自分と他者を理解するためのモバイルノートアプリ
PPTX
生成AIとモデルベース開発:実はとても相性が良いことを説明します。まあそうだろうなと思われる方はご覧ください。
PDF
翔泳社 「C++ ゼロからはじめるプログラミング」対応 C++学習教材(三谷純)
PPTX
Cosense - 整えずして完全勝利!Cosenseが他のwikiツールと違う理由
PDF
R-SCoRe: Revisiting Scene Coordinate Regression for Robust Large-Scale Visual...
PDF
20250826_Devinで切り拓く沖縄ITの未来_AI駆動開発勉強会 沖縄支部 第2回
PDF
Yamaha DT200WR Real Enduro ENGINE CYLINDER TRANSMISSION
PDF
Geminiの出力崩壊 本レポートは、Googleの大規模言語モデル「Gemini 2.5」が、特定の画像と短文入力に対して、誤った地名を推定し、最終的に...
PDF
20250823_IoTLT_vol126_kitazaki_v1___.pdf
PDF
Working as an OSS Developer at Ruby Association Activity Report 2025
ココロ分解帳|感情をやさしく分解し自分と他者を理解するためのモバイルノートアプリ
生成AIとモデルベース開発:実はとても相性が良いことを説明します。まあそうだろうなと思われる方はご覧ください。
翔泳社 「C++ ゼロからはじめるプログラミング」対応 C++学習教材(三谷純)
Cosense - 整えずして完全勝利!Cosenseが他のwikiツールと違う理由
R-SCoRe: Revisiting Scene Coordinate Regression for Robust Large-Scale Visual...
20250826_Devinで切り拓く沖縄ITの未来_AI駆動開発勉強会 沖縄支部 第2回
Yamaha DT200WR Real Enduro ENGINE CYLINDER TRANSMISSION
Geminiの出力崩壊 本レポートは、Googleの大規模言語モデル「Gemini 2.5」が、特定の画像と短文入力に対して、誤った地名を推定し、最終的に...
20250823_IoTLT_vol126_kitazaki_v1___.pdf
Working as an OSS Developer at Ruby Association Activity Report 2025
Ad

READMEを書こう