Как правильно вставлять картинки в документацию

Когда люди пишут документацию, они часто добавляют в неё скриншоты и другие изображения. Осуждаю и советую всеми силами избегать. Даже очень крупный бизнес типа Google и Yandex избегает скриншотов, а картинки в 99 случаях из 100 можно заменить текстом.

Скриншоты

Почему скриншоты не нужны

Скриншоты не нужны в первую очередь потому, что их дорого поддерживать.

Допустим, вы создали 20 скриншотов, на которых везде торчит главное меню. В какой-то момент разработчики добавили туда новый пункт. Это значит, что вам нужно:

Проверить все скриншоты во всей документации.
При необходимости сделать устаревшие скриншоты заново.

Когда их 20 штук, задача не выглядит сложной. А когда их 50? 100?

Десятки часов работы, притом работы ненужной.

Почему скриншоты нужны

Иногда без скриншотов не обойтись. Например, вы должны описать основные элементы управления. В этом случае я рекомендую сделать так:

Создайте скриншот, на котором будет видно максимально возможное количество элементов управления.
Расставьте выноски.
Опишите выноски.

Пользователи сразу поймут, где какой элемент находится и как называется. Это можно сделать один раз. Не нужно потом в каждом разделе с нуля описывать: «Это кнопка отмены. Если её нажать, операция будет отменена». А то мы бы без подсказки не догадались!

Выводы по скриншотам

Избегайте.
Если делаете скриншоты — делайте их только тогда, когда без этого вообще невозможно обойтись.
Не забудьте убрать со скриншотов критичные данные.
Делайте скриншоты достаточно большими, чтобы их можно было нормально рассмотреть.

Картинки

Просто расскажу про дичь, которую встречал в разных местах.

Насколько сложно в HTML сделать кнопку с надписью “Вперёд”? Вы думаете, это решение?

<button class="btn btn-default">Вперёд</button>

Как бы не так!

При разработке портала Госуслуг для Липецкой области УВАЖАЕМЫЕ РАЗРАБОТЧИКИ наверстали примерно такое:

<div>
  <span style="display: block;">
    <div style="width: 120px;">
      <div style="display: block; float: left; width: 100%">
        <button style="display: block; width: 100%; height: 100%;">
          <span>
            <image src="/resources/static/images/buttons/vpered.jpeg" width="100px" height="20px;"></image>
          </span>
        </button>
      </div>
    </div>
  </span>
</div>

К сожалению, это не единственный случай. Иногда люди вставляют картинки в документацию.

Вёрстка здорового человека:

Нажмите кнопку **Вперёд**.

Вёрстка наркомана:

Нажмите кнопку ![widht=100px;height=20px](/static/images/00253215321.jpg)

Тут сразу несколько проблем:

Почему бы не написать название кнопки просто текстом? Кому нужны эти зашакаленные джипеги?
Почему имя файла ничего не говорит о содержимом?

Выводы по картинкам

Именуйте файлы нормально. У каждого файла имя должно быть таким, чтобы было понятно что внутри ещё до просмотра содержимого.
Раскладывайте файлы по каталогам. Жопа у вас от этого не отвалится, а найти нужное станет легче.
Не используйте картинки там, где можно обойтись простым текстом. Вставляя картинку, вы только усложняете себе жизнь. Пользователи не оценят.