Как писать документацию, которую захотят читать

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

Давайте выделим основные принципы, которые сделают доки понятными и полезными:

1. Читаемость и компактность. Текст должен быть кратким и понятным. В инструкции "Открыть терминал. Ввести команду Х" звучит лучше, чем "Запустите командную строку и выполните следующую последовательность действий". Чуть полнее этот тезис я раскрывала в посте "ТЗ должно быть полным, но кратким".

2. Структура. Документация должна быть структурированной. Используем заголовки, подзаголовки и списки. Если есть несколько разделов, обязательно добавляем в начало оглавление. Читатель сразу увидит, где искать нужную информацию.

3. Выразительность. Пишем просто и ясно. Избегаем сложных терминов, если в этом нет необходимости. Если нужно использовать сложные термины, обязательно объясняем их. Так читатель не запутается.

4. Конкретность. Используем конкретные примеры. Это помогает лучше понять написанное. Например, если объясняем, как подключиться к базе данных, приводим примеры кода и скриншоты. Это лучше, чем абстрактное описание.

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

6. Комментирование. Не забываем про комментарии. Хорошие комментарии помогут понять сложные моменты. Например, если есть сложный кусок кода, объясняем, что он делает (а не ждём, что читающий с одного беглого взгляда всё поймёт). Это сэкономит время читателю.

7. Обновляемость. Важно регулярно обновлять документацию. Устаревшая информация может привести к ошибкам. Нет ничего хуже, чем протухшее описание логики витрин или некорректные инструкции по подключению. Для сохранения истории используем контроль версий.

8. Визуализация. Добавляем схемы, диаграммы, скриншоты. Визуальные элементы помогают лучше понять информацию. Например, если есть сложная архитектура системы, добавляем схему. Это лучше, чем длинное, запутанное текстовое описание.

9. Инструменты. Используем инструменты для написания документации. Это могут быть редакторы с поддержкой разметки, системы контроля версий и/или платформы для совместной работы. Чуть подробнее об инструментах я писала здесь.

Следуя этим простым принципам, документация станет в разы более полезной и удобной.

#документация