＊この記事はReadmeでやってはいけないことをまとめてみたジョーク記事です
実際のリポジトリも公開していますが全て架空の案件・出来事です
今回作ったリポジトリ
最初に
Github、みなさん使っていると思いますが、Readmeの作り方は会社、案件、個人個人によるレベルで様々です
「良い方法」というのはチームでブラッシュアップしていくもので、固定の正解はないものですが
仕事でコンテンツを作っている以上、やっては行けないこと、こういうものは困る。といったものが多く出てきます
今回はジョーク的に、リポジトリ内の記載の何が行けないのかを記載していこうと思います
1.リポジトリの説明はNDA気をつけて！
まずはトップのリポジトリの説明部分からです
クリックしてみるとイカのような画像が飛び込んでくると思われます
まずリポジトリの最初に、デカデカと受託した案件の会社名、タイトルと画像が出てしまっています
リモートワークも盛んな昨今、このように一眼で案件やタイトルが特定できることは、
ちょっと後ろを通った人が色々と把握できてしまうので良くないです
自社タイトルならまだ良いかもしれませんが、少なくともここに画像をドーン！ と置いてしまうのは良くはないと思っています
ここはあくまで社内ならわかる程度に、具体的なものは置かないようにしましょう
2.インストール方法はなるべく簡潔に！
次に、インストール方法です
案件をやっていると、どのツールをどうインストールしていくか。の情報はスムーズな環境構築のためにも記載は必須です
ではこのアンチパターンではどうやっているかみてみましょう
見るに堪えないので縮小しました
ここで説明しているのは、Unityのダウンロードを画像付きで丁寧にクリックごとに教えています
そう言ったものはインターネットができる人なら誰でもわかることです
また、もしUnityがサイトのレイアウトを変更した際に画像での説明は混乱の元になるので
画像はあっても、わかりにくい場合の注釈程度にしておきましょう
また、流れを文字で説明していればコピー＆ペーストも可能なので、今回はUnityですがコマンドラインでインストールする場合は実行するコマンドの流れを明確にすると良いでしょう
3.説明のスタンスは一貫性を持って、力を入れるところは間違えないように
インストール方法のところをみると、Unityのダウンロードが終わった瞬間に説明が雑になっていると思われます
3.最新版をInstallします。次の画面で必要なやつを選択してインストールます
はい。画像を作る労力が無くなってしまったようです
しかも見ている人が本当に知りたいのは、この後にどの選択をしてインストールしたらいいか。です
力を入れるところはちゃんと力を入れ、力を抜くべきところは全力で抜きましょう
また、画像での説明をするのなら一貫して画像を入れておくべきです
途中で画像が無くなると、縦幅的に読み飛ばされる危険もあります
また、画像つきの細かい説明はReadmeではなくWikiなどに書くと良いでしょう
4.「最新版」という単語は使わない
先ほどスルーしてしまいましたが、
3.最新版をInstallします。次の画面で必要なやつを選択してインストールます
Readmeに置いて、この「最新版」という単語は非常に厄介です
書いた時点では最新版かもしれませんが、時は流れていくものです
1年後にはバージョンアップしている可能性が高いので、「最新版」ではなく、ちゃんとバージョンは明記しましょう
5.誤字には気をつける
インストールの項目が長くなってしまいますが、インストールの最後の項目をみてみましょう
4.このプロジェクトをCloseして開きます
はい。どうやらCloneの誤字のようです。誤字があるのは仕方ないことですが、プロジェクトのCloseはそれ単体でも意味は通じてしまうため
今からインストールするぞ！ という新メンバーはこの部分を見て混乱することでしょう
重要な誤字、意味が通じなくなるレベルの誤字はなるべく直しましょう
6.仕様書の情報は気をつけて！
次に仕様書の欄です
仕事をしている以上、何を作るのかの認識を合わせる以上、誰もがアクセスしやすい位置に仕様書のリンクを置くのは良くあることです
それでは記載をみてみましょう
New! 2021年9月23日更新 ・社外から仕様書見れなくて不便との声が多かったので、リンク知ってれば誰でもみえるように設定変更しました
https://docs.google.com/document/d/1D1oLLTT_fNF9Bq3O-Hw-jhZCdvBXpTvdP2b0Zxmmao0/
先ほどと違い、ちゃんと更新日付は書いてありますね
ただしこの日付が仕様書の更新日付なのか、システム的な更新日付なのかが不明なので、もうちょっとわかりやすい表記が良さそうですね
1年以上前の日付の New! も哀愁があります
また、情報漏洩の危険がここでもあります
プロジェクトの仕様書は機密の塊になりますので、社内ネットワークからのアクセスが難しい場合でも、せめてユーザの認証は入れましょう
7.コーディング規約の例
次にReadmeのコーディング規約です
実装を円滑に進めるため、コーディング規約を決めていることは多いです
また、git-flowなど、凝り固まった規約があるならそれを使うことを明言しておけば、規約の認知もスムーズになります
ここでは以下のように記載されていますね
以下のサイトを参考にお願いします
https://sites.google.com/view/mounaisaitodesuyo/%E3%83%9B%E3%83%BC%E3%83%A0
ではこのサイトにはどういった手法が載っているのでしょう。新しく入ったメンバーはワクワクしてクリックすることでしょう
サイトが半年前には閉鎖されてしまっていました
参考にしているサイトのリンクが無効になってしまうことはよくあります。諸行無常
しかし、以下のサイトを参考に。と書いてあるだけでどう言った手法が取られているのかが不明です
この場合は、以下のサイトを参考に。というところは良いのですが、手法の名前などを併記することでサイトの閉鎖や移転があっても、なんとか追いかけることはできると思います
8.頼りになる人の情報は特定可能に！
ヘルプの項目を見てみましょう
インストールや導入、リンク切れなどの問題で環境構築やキャッチアップがうまくいかない場合、
誰に聞けば良いのか、どのチームに聞けば良いのかを記載することはよくあります
新メンバーはそこもわかりにくいですからね
そして今回の記載は
導入や起動方法などに困ったら山田までご連絡ください
どの山田ですか…？ となりますよね
特に大きい会社では社内に、もしくは案件内にも鈴木さん、高橋さん、山田さんなどよくある苗字の方は溢れることになります
また、このプロジェクトのメンテナンスのされてなさをみるに、この山田さんが社内にまだいるかも疑いを持ちます
こういった場合は個人名ではなく、チーム名やチャットツールの質問場所などを記載すると良いでしょう
9.機密情報ワーニング
いよいよ最後です。ヘルプの下の方に太字で以下のように書かれています
これは最初に書くべきですし、極秘なら画像やリリース日、セキュリティなどの情報は気をつけましょう
最後に
このReadmeは大きく次の問題があります
- 情報の漏洩リスク
- 欲しい情報が結局書かれていない情報制度
- メンテナンスされていない情報の不確かさ
Readmeで全てをカバーしようとすると、Readme自体のボリュームも膨れますし
機密情報にもReadmeを読むだけで簡単にアクセスできてしまいます
なので、あくまでもReadmeは導入する程度にとどめておき、他の重要な情報や詳細な情報はReadmeとは別の管理を一考するべきと私は考えています