エンジニアの為のREADMEの書き方

この１年で視力が激落ちした、ユゲタです。 ずっと1.0以上はキープできていたのに、今年は0.5と0.6、左右で違う視力もよろしくない上、来年の健康診断まで、ホットアイマスクと、視力回復運動を一生懸命行おうと心に決めた結果でもありました。 どーりで最近読書していたら目がかすむと思ってたんだよね。 でも、読書も好きなので、視力は絶対に悪くしたくないんだよね〜。 そして、読む以上に、書くこともとても重要という事が今回のテーマです。

できるプログラマーはドキュメントスキルも高いという事実

これまで、会社のシステムを作ってきた時に、ドキュメントを避けてきていて、製品製作（開発）と製品マニュアルは別の人が担当することがほとんどで、ドキュメンテーションなどは人任せにしていたのですが、 最近Githubに自分の作ったOSSをアップしているときに、過去に作ったモノにアクセスしてみたら、なんだかよく分からない上に、こんなプログラム誰が参考にして、誰が使うのか、というクソっぷりがよく理解できました。 何となく概要だけ書いてあるREADME.mdを設置することだけを考えていたんですが、ここの書き方をしっかりするだけで、利用者の気分が大きく変わるというのは、マーケティングを長らく仕事でしてきたのに、今更ながら気がついてしまいました。 そして、思い起こせば、プログラムのスペシャリストの人達は、こうしたドキュメントをしっかりとこだわって作り込んでいたことを思いましました。 個人で使っているGithubは、自分でドキュメントもクオリティ対象になるという事を理解しておきましょう。

READMEはこう書け！

とりあえず、他の人の書いてあるREADMEで使いやすいもの、使いにくいもの、見やすいもの、見にくいものを、自分なりに研究して、以下のようなレギュレーションにたどり着きました。

1. Authorを冒頭に記述

Githubは、アカウントがトップディレクトリになっているので、不必要に思われるかもしれませんが、リポジトリをcloneした時に、READMEを見ると、この記述がないと、誰のプログラムなのか、全くわかりません。 READMEドキュメントだけじゃなく、チーム複数人でプログラムを書いているときには、コードの冒頭にコメントで書き込むという手段も悪くないですね。 （無駄パケを無くすために、min化しないといけないですけどね・・・）

2. DateはHistoryとセットで結構重要

OSSのプロジェクト開始日、機能追加、改修日、どういうタイミングで、何を行ったかというHistoryは"git log"にまかせていてもいいのですが、 READMEにかかれていると、簡易に見られて助かる事が多いです。 Gitのtag管理がちゃんとできている人であれば、こうしたHistory管理は、十分に行えているから、コピーでもいいので書いてあると、いいかもです。

3. Summaryは簡易にわかり易く！

当たり前ですが、「概要」はわかり易くなくてはいけません。 文章で書くよりも、箇条書きで、「何が出来る」「ツールの説明」を書くぐらいでもいいのですが、長い文章を書くとそれだけで、そのツールを使う気が失せます・・・

4. Howtoが一番重要

使い方について、全く書かれていないREADMEもありますが、マニュアルとして全く意味をなしていません。 どういう環境でどのように使うのかを明確に手順を記述してあげることで、利用者は楽にセットでき、そのツールを便利だと感じてくれます。 使い方が間違っていると、製品クオリティ自体の品質も落ちる印象を与えるので、気をつけましょう。

5. RequestとIssueもあるとより良い

そのツールに対して、現在ない機能だがユーザーが欲しがっている機能は、Pull Requestと同じになるかもしれませんが、記述してあった方が、製作者の人の思考が行き届いている事が理解でき、クオリティアップにも繋がります。 同時にIssueを細かく書いて、それを解消しているかチェックを付けることで、キチンと管理・運用されている印象も受けられます。 プログラマーとしては、類似のプログラムエラーに関する知見も広がるので、この項目が書かれているとついつい見てしまいますね。

6. Explanation（解説）

プログラムの内容や、UI/UXなどに関してのプログラマー視点の解説文章は、非常に参考になることも多く、クオリティに直結するため、この内容があると、結構なアピールポイントにもなります。 必要かというとそうでも無いのですが、あるとより便利でしょう。

7. バナー（画像）を付けよう！

ブログと一緒でアイキャッチのような画像を付けることで、数あるOSSプロジェクトの中で目を引くポイントになります。 凝った画像にする必要はなく、画面キャプチャでもいいし、印象が分かる程度のアイコンでもいいかもしれません。 個人的には、SVGをフリーサイトからDLして、色味を調整してバナーを作成しています。 OSSの数が増えた時に、こうしたバナーのカラーリングなどの法則性があれば、全体としていいプロジェクトになるかもしれません。

英語の勉強してみませんか？

グローバルを見据えている訳ではないですが、僕のREADMEは、ところどころ英語で書かれています。 これは単純に、個人的に怜語の勉強の一環として、文章を書く時に英語にしているだけなのですが、 Githubにアップすると、海外の人も結構見てくれる事が多いため、英語で書いてあることでのメリットもあるかもしれません。 英語でメールを貰ったこともあるし、twitterでメッセージを貰ったこともあるので、英語の読み書きもちろんのこと、海外の人も見たり使ったりすることを意識しておく必要はありますね。

最後に

README.mdはマークダウン言語で記述するのですが、この言語は非常に簡易にWEBページ構成が記述できるので、こうしたドキュメント系で使われる事が多いようです。 使い慣れておくと良いことも多い上、「ドキュメントに時間をかけるのはナンセンス」という人もいる中、時間効率化と、クオリティアップに貢献できるスキルになるでしょう。 備忘録としての、自分メモ程度のドキュメントもいいのですが、他人がそれを読むことを意識すると、レギュレーションを作っておくことは非常に重要に感じられました。 もちろん、これが全て正解というわけでもなく、他にももっと効率的に高品位な記述があるし、要所要所に自動化できるポイントなどもあるので、今後もレギュレーションは変化していくと思いますが、今現在は、こうしたドキュメンテーションを信じて活動しています。 ブログもマニュアルも、下記慣れることで仕事の幅が広がる感覚も得られました。 「人に見られてなんぼ」という意識、結構重要ですよ。