はじめに
こんにちはあるいはこんばんは！
残暑もようやく影を潜め、秋らしくなって過ごしやすくなりましたね！季節も変わって心機一転、新たな取り組みや勉強も始める方もいるかもしれません。
僕も新たにRustでも入門してみようかなと読みふけっています。
ところで皆さんは自分で開発したツールやアプリのREADMEは書いていますか？
自分用で開発すると意外とちゃんと書ききれていなかったりするのではないでしょうか？
書き方がいまいちわからないとか、何が正解なのかと手をこまねくかもしれませんが、みなさんのアウトプットをより良くするためにもREADMEを残しておくことはとても大事なことです。
ということでREADMEを書く上で意識すると良いところをまとめてみました。
READMEとはなにか
ではまず、READMEとはなにか。
簡単にいうと、プロジェクトを適切に使用するためのガイドを担うワンストップドキュメントです。
これはつまり、README一つでそのプロジェクトを説明することができるドキュメントであるということです。
多くは、プロジェクトのインストール方法、実行方法や実行環境などを説明します。
誰に向けて書くものか
（個人的にこれが一番難しいのですが）
ドキュメントと呼ばれるものを書く上で重要な要素の一つは、「読み手の事を考えること」です。
そのドキュメントはどんな人のためのもので、どんな人が読むものなのか。
これはREADMEに限った話ではないですよね。
丁寧なドキュメント書いてくれる方はこの辺をよく心がけてくれているなぁと感じることが多いです。
自身が作成したプロジェクトやアプリを対象にした場合ですと、以下のようにカテゴライズされると思います。
- エンドユーザー（End users）
属性としては、あなたのプロジェクトやアプリ、ツールの利用者。機能の側面を重視する。
技術的な知識を有していない方。技術的な実装に対する関心は薄い。 - テクニカルユーザー（Technical users）
属性としては、技術者あるいは技術的な面に関心を持つ方。もしくは自身のプロジェクトに統合させたり、APIやライブラリとして使いたい方。提供される機能に対する関心は強いが、実装内容については関心が薄い。 - 貢献者（Contributors）
属性としては、あなたのプロジェクトと関わり・交流を持つ方。
プロジェクトやアプリ、ツールをインストールするためのサポート、バグや新しい機能を提案する方。あるいは拡張機能を含むプルリクエストを送信したいユーザーや経済的にプロジェクトを支援したい方。
提供先によってはもっと細かく定義する必要があったりすると思いますが、これらの対象を一つのグループとして含んで考えるといいですね。
また、内部での資料でない限り、言語は英語で統一するようにしましょう。
母国語のみのREADMEは公開するにあたり、親切ではないので、、
フォーマットと書き方
READMEはMarkDownで記述しましょう。
多くのホスティングサービス（github、gitlabなど）でMarkDown構文がサポートされていますし、実際みなさんが目にするREADMEのほとんどがMarkDownで記載されていると思います。
「人々は読むのではなく、スキャンする」という公理に基づき、Markdownを適切に使用することで、ドキュメントに視覚的な構造を与え、ユーザーがファイルの内容をスキャンしやすくすることができます。
How Users Read on the Web
https://www.nngroup.com/articles/how-users-read-on-the-web/
Summary: They don’t. People rarely read Web pages word by word; instead, they scan the page, picking out individual words and sentences.
By Jakob Nielsen on September 30, 1997
Topics: Writing for the Web
(余談ですが、先日ドキュメントの書き方を学んでいた際にも似たような内容で「ドキュメントはすべて読まれることを想定してはいけない」旨が記載されていました。)
では、どう書けばよいのか。
テキストをオンラインで読む方法、つまりは「スキャンする」、「検索する」に適応させるためのWeb用のいくつかの基本原則に沿って書くようにします。
- 短い段落を使用する。3～5行程度が目安です。各段落には1つの概念しかないようにします。そうすることで、スキャニングがしやすくなります。
- 箇条書きまたは番号付きのリストを使用してください。
- click hereリンク（いわゆる「こちらをクリック」）は使用しないでください。意味のあるテキストを使用しましょう。
click hereリンクを使用すると、ユーザーはリンクの前後の脈絡や文脈を読む必要があります。 - キーワードや文章の段落は太字で強調する。下線はリンクと混同される可能性があるため、使用しないようにしましょう。
- 各段落で最も重要な情報から始める。文章には逆ピラミッド構造を使用しましょう。
読み手にとって、最も重要な内容から始め、その後に追加の情報を提供するような構成にしましょう。
以下については、今回挙げた基本原則の中でも紹介されていますが、いずれも目を通しておくと理解が深まると思います。
READMEの内容
誰のために書くか、提供するドキュメントの構造・形式についての慣習が整理できたところで推奨される構成で内容を整理します。
- 提供するプロジェクトがどのようなものか簡単に説明する。
- インストール方法と実行方法を記載する。
- 訪問者にどのようにプロジェクトに参加し、どのように協力できるかを提供する。
この構成は、これまで紹介した各カテゴリーのユーザーから期待される、プロジェクトへの関与の度合いに沿っています。
例えば、エンドユーザーはただプロジェクトについて知りたいだけですので、１と２が対象になりますね。
多くのプロジェクトでは上記以外に用意すべき内容があると思いますので、必要に応じて内容の要素は増やしても良いでしょう。
いずれにせよ、上記の構造は最低限適用させるべきと考えます。
具体的な内容はプロジェクトの動機や経緯、解決する課題、使用することへのメリット、あるいはプロジェクトで学んだ内容などから考えると記載しやすいのではないでしょうか。
ここまでの内容を踏まえて、READMEに以下のような項目を用意するとよいかと思います。
- プロジェクトのタイトル
- プロジェクトの説明
- 目次
- プロジェクトのインストール方法、実行方法
- プロジェクトの使用方法
- 謝辞（貢献してくれたチームメンバーの名前、参考にしたプロジェクトへのリンクや資料などの情報）
- ライセンス
- プロジェクトのステータスバッジ
- プロジェクトへの貢献方法、行動規範
また、READMEを自動で作成してくれるオープンソースプロジェクトを利用するのも良いかと思います。
さいごに
最後になりますが、READMEに唯一の正解は存在しません。すべてのプロジェクトに独自な考え方を含んだ、ユニークなガイドになって良いと思います。
ですが、今回挙げたようなドキュメントとしてのルールや慣習に沿うことは一定のクオリティを保つ上で遵守すると良いですね。
優れたREADMEをまとめたリポジトリもあったので、こちらもぜひ参考にしてみてください。
ここまで読んでくれてありがとうございました！
それではまた！
