Readmeを書くことは良いことずくめなんじゃないか
意外とReadmeを書こうという記事を見たことがあんまり無いので書いてみます。
Readmeの唯一の欠点は、「基本的にあまり読まれない」ことなんですが、でもそれ以外では良い事がたくさんあると思います。作る前から/作りながら書いても良いと思う。でも書いてみて初めてわかることばかりなので、自分の経験からメリットを書いてみます。
一つ。最初から最後の事を考えておくべきだ。
とりとめがなくなることを防ごう。リリースするためにプログラムを書いて、少なくとも最後にはReadmeを添えよう。ただの趣味ならいいけど。
一つ。ある程度の著作権知識も身につく
フリーだとしても公開物は全てライセンスを考えておかなきゃいけない。Readmeに含めるかは微妙だけどどっちみち必要。コピペするにしても少しは読まなきゃいけないし、多少はググらなきゃいけない。実はそれだけでもけっこう知識が身につく。
一つ。YAGNIの基準に出来る。
ある機能の拡張方針で悩んでいるとする。そんな時は、Readmeに使い方を書きやすいように設計しよう。落ち着いて操作手順を推敲したとする。Readmeはただのテキストだから詰め込める情報は結構少ないけど、それでもその制約下でうまく簡単に説明できない時は、そのアイデアはちょっとアレゲな疑いがある(*1)。
一つ。やむなくアレな仕様を採用せざるを得ないとして、被害を最小限にするため、詳しい使い道をプログラムの外の手順書や注意書きにしてしまう手もあるじゃない
たまに、アレな仕様だけどハードの制約とかで採用せざるを得ない場合。そのアレな追加仕様のせいでいろんなところに修正項目が大きく波及してしまうなら、ちっと考えてみて、もしそれがレアケースとかなら、何もボタン一個でプログラムが内部で全てファジーに対応するとか、専用の特殊モードが発動するような話ではなく、手順書に注意書きを目立つように、あるいは検索可能に残しておくだけで良かったりするんじゃないの?
一つ。エラーメッセージ一覧
きちんとしたプログラムはエラーに強い。エラー設計がきちんとされているなら、エラーメッセージ一覧を作るのもきっと簡単。そしてその一覧はユーザーにとってすごくありがたい。一方、エラー時のシナリオがボロボロなプログラムはエラーメッセージ一覧を作るのも大変だ。一覧がなければユーザーはマニュアルを自分でスミズミまで読み直す羽目になる。よくない。
他にもあるんじゃないかなと思いますが、とりあえずこんなところです。なんかすんごい泥臭い話になっちゃったな…