joucho archive / technology / 55.02

cat technology/README.md

README

この文書について

これは、README という形式そのものについての観測記録である。

ただし、READMEについて説明するためだけの文書ではない。
READMEという形式を借りて、READMEの情緒をそのまま置いておく。

コードはまだない。
インストール手順もない。
使い方もない。

それでも、最初に読むものだけが、ここにある。

名前

README

この名前は命令に近い。

読め、ではなく、読んでください、でもない。
ただ、そこに大文字で置かれている。
ディレクトリを開いた者が、最初に目を合わせるように。

由来

README は、古いUnix文化の中で、配布物やディレクトリの入口に置かれる案内として定着した。

中身を読む前に、まずこれを読む。
コンパイルする前に、まずこれを読む。
誰が作ったのか、何をするものなのか、何に注意すべきなのか。

大きなマニュアルではない。
すべてを説明する文書でもない。

むしろ、まだその場所に慣れていない人間へ向けた、最初の短い声である。

README.txt

README.txt には、素の文字だけがある。

装飾はない。
見出しも、リンクも、バッジもない。
等幅の文字が、平らな画面の上に並ぶ。

そこには、インストーラの前に開かれる紙片のような感じがある。
zipファイルの中に残された注意書き。
フロッピーやCD-ROMの端に置かれた、最後の人間語。

読む者は、それを美しいから読むのではない。
そこに何か大事なことが書いてありそうだから読む。

README.md

README.md は、同じプレーンテキストでありながら、少し外を向いている。

Markdownによって、ただの文字列は見出しになり、リンクになり、コードブロックになる。
GitHubの上では、それはリポジトリの玄関になる。

プロジェクト名。
説明。
インストール方法。
使い方。
ライセンス。
コントリビュート方法。

それらが並ぶことで、コードの束は、誰かを迎え入れる場所になる。

README.md は、もはや単なる説明書ではない。
それは、プロジェクトが外部に向けて最初に差し出す顔である。

観測

ディレクトリの中には、多くのファイルがある。

実行されるもの。
読み込まれるもの。
生成されるもの。
隠されるもの。
壊してはいけないもの。

その中で、READMEだけが、最初から人間のために置かれている。

機械に読ませるためではない。
処理系に渡すためでもない。
依存関係を解決するためでもない。

そこに来た誰かが、迷わずに済むように。
あるいは、少しだけ迷い方を知るために。

READMEは、コードの前に立つ。

まだ実行されていないもの。
まだ理解されていないもの。
まだ信用されていないもの。

その入口に、READMEはある。

使い方

この文書は、次のように読む。

1. まずタイトルを見る。
2. それがREADMEであることを確認する。
3. 説明を読んでいるうちに、説明されている対象がこの文書自身でもあることに気づく。
4. READMEが、単なるファイル名ではなく、入口の作法だったことを思い出す。

参照

• GNU Coding Standards: Distribution files such as README, INSTALL, NEWS, COPYING
• John Gruber, Markdown
• GitHub Docs: About READMEs
• GitHub Flavored Markdown Specification

最後に

コードは機械に向けて書かれる。

READMEだけが、最初から人間のためにそこに置かれている。

——観測終了。