【すぐできる】プルリクやコメントなどで画像を使うとき、読みやすくするちょっとしたアイデア

はじめに

本日もプルリクエストお疲れさまです！
私もプルリクやらレビューやらコメントやら何やら、日常的に書いております。

またその中でイメージを伝えるためにスクリーンショットなど画像を埋め込む、という作業もよくされているかと思います。そこで今回は、見せ方を考えるだけで読みやすくなるかも！っと個人的に思ったことをまとめてみました。何かの参考にでもなれば幸いです。

画像にキャプションをつける

その画像が何を表しているのか。複数の画像があるときは特に効果的です。
が、容易に推測できる場合でも、明記した方が読みやすくなります。

キャプションなし

キャプションあり

ドロップダウンのイメージ

キャプションには方向を表すマークをつける▼▲

この画像がどのキャプションかが明確に分かるように、▼や↓のように方向マークをつけるとさらに分かりやすくなります。一瞬でも迷うのは意外とストレスです。

方向マークなし

ドロップダウンのイメージ

方向マークあり

▼ ドロップダウンのイメージ

キャプションを画像の上と下どちらにつけるかは、悩ましいかもしれません（詳しくは下記ページを参照）。
図のキャプションは下に、表のキャプションは上に書くのが原則。JISもある

画像に枠線をつける

テキストが多く含まれていたり、背景が白色だったり、ピンポイントにトリミングしたり...どこまでが画像かパッと見て分からなくなることがあります。その場合は枠線などで画像エリアを視覚的に表現すると親切です。

どこまで画像なのか...

Aさん: 内容の確認をお願いします！

▼ フォームのモックイメージ

画像に枠をつけるだけで

Aさん: 内容の確認をお願いします！

▼ フォームのモックイメージ

どうやって枠をつける？

では枠線はどうやってつけるのが楽でしょうか。

1. <style> を使う（使えれば）
2. キャプチャするときに枠線を作る
3. 画像を加工する
4. マークダウンで無理やり再現する

1がベストですが、できないことも多いです。
2, 3はやや手間が掛かりますし、gifアニメなどは難しいです。
4は例えばtableの中に入れると再現できます（qiita, githubの場合）

▲ フォームのモックイメージ

text.md

| 画像 |
|:---|
| ▲ フォームのモックイメージ |

当然こんな感じのタグで出力されてしまいますが...html

<table>
  <thead>
    <tr>
      <th style="text-align: left">
        <a href="xxx.gif"><img src="xxx.gif"></a>
      </th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td style="text-align: left">▲ フォームのモックイメージ</td>
    </tr>
  </tbody>
</table>

※ちなみにこれがベタ貼りだと

比較できるものは並べる

before/after のように、それぞれ比較すると分かりやすくなるものは変更前のキャプチャも貼って、左右に並べると分かりやすいです。

▼ 行の余白を少し広くしたイメージ

before	after

ただ画像が大きくて縮小されて見にくくなったり、逆に縦並びの方が良いこともあるので、ケースバイケースですね

おわりに

以上、単純なものばかりですが、本文の分量が増えてくると意外と効いてくるかと思います。
他にもこんな工夫しているよ！とかあれば、ぜひ教えてください！