Документация — это не скучно, а спасение для вашего будущего "я"

«Программы должны быть написаны так, чтобы их могли читать люди, и лишь случайно — чтобы их могли выполнять машины». — Дональд Кнут

Вы наконец доделали проект. Часы отладки, десятки вкладок со Stack Overflow, одна ошибка за другой — но всё заработало. Вы пушите код на GitHub, закрываете ноутбук и забываете.

Через несколько месяцев возвращаетесь, чтобы добавить новую фичу. Открываете репозиторий. Десятки файлов. Переменные с названиями, которые тогда казались гениальными. Теперь — нет. Листаете свой же код, пытаясь вспомнить, почему выбрали именно этот подход.

И задаёте вопрос, который знаком каждому разработчику: «Кто это написал?»

Вы.

Если узнали себя — вы уже поняли, зачем нужна документация. Вы пишете её не для препода, не для начальника и не для коллег. Вы пишете её для себя в будущем — для того, кто забыл всё, что вы знаете сейчас.

Главный миф о документации

Большинство разработчиков считают документацию тем, что пишут после завершения проекта. Именно из-за такого подхода проекты остаются без документации — «потом» редко наступает.

Документация — не финальная глава. Это часть процесса создания. Вы же не ждёте, пока дом построят, чтобы начертить план? План направляет строительство. Документация делает то же самое для кода: фиксирует решения и объясняет ход мыслей по ходу работы, а не постфактум.

В GitHub подтверждают: README должен объяснять, что делает проект, зачем он нужен, как начать, где получить помощь и кто его поддерживает. Потому что для большинства посетителей это первое, что они видят, и оно формирует впечатление о проекте.

Что такое документация на самом деле

Скажите «документация» — и люди представляют толстенный технический мануал. Иногда это так. Но чаще — гораздо проще:

• README
• Инструкция по установке
• Комментарий, объясняющий хитрую логику
• Заметка по устранению неполадок
• Список изменений (changelog)

Документация — это любая информация, которая помогает понять ваш софт. И «кто-то» — это можете быть вы через полгода, коллега, контрибьютор или рекрутер, просматривающий ваш GitHub. Хорошая документация отвечает на вопросы до того, как их зададут.

Почему мы её пропускаем и чем это аукается

Документация — не самое захватывающее занятие. Наблюдать, как наконец запускается приложение, — вот это кайф. Писать README — нет. И новички говорят себе: «Задокументирую потом», — а «потом» не наступает.

Когда вы возвращаетесь к проекту, вы уже забыли, почему выбрали ту библиотеку, что на самом деле возвращает функция, какие переменные окружения нужны и какая команда исправила вчерашний баг. Приходится решать одну и ту же проблему дважды — время, которое можно было потратить на что-то новое.

Моника Пауэлл, звезда GitHub, называет личную документацию «вторым мозгом»: вместо того чтобы каждый раз искать ответ заново, вы записываете его один раз, понятно для себя, и используете снова. Это стоит тех пяти минут, которые вы потратите.

Скрытая цена плохой документации

Представьте два репозитория.

Репозиторий А:

README объясняет, что делает проект, как его установить, запустить и как внести свой вклад. Вы клонируете — и через пять минут уже работаете.

Репозиторий Б:

И всё. Ни инструкций, ни примеров, ничего.

Какой из них вызывает больше доверия? В какой вы захотите внести вклад?

Исследователи, изучившие тысячи репозиториев на GitHub, обнаружили, что README часто формирует первое впечатление разработчика о проекте и определяет, сможет ли он вообще разобраться, как им пользоваться. Документация создаёт доверие ещё до того, как кто-то откроет ваш код.

Документация делает вас лучшим разработчиком

Легко думать, что документация нужна только другим. Нет. Когда вы её пишете, вы вынуждены отвечать на вопросы:

• Какую проблему это на самом деле решает?
• Почему этот подход, а не другой?
• Что я предполагаю, что читатель уже знает?

Если вы не можете объяснить свой проект понятно — вероятно, вы не так хорошо его понимаете, как кажется. Запись мыслей заставляет упорядочить их.

Хорошая документация — короткая, не исчерпывающая

Ещё одно заблуждение: хорошая документация означает много документации. Нет. Она означает правильную информацию.

Команда документации GitHub рекомендует писать простым языком, быть кратким и структурировать текст так, чтобы его можно было быстро просматривать, а не описывать каждый возможный случай. Один понятный абзац или пример кода часто учат большему, чем три страницы текста. Количество не цель, ясность — да.

Привычка, которую можно завести сегодня

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

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

За пределами README

README — входная точка (так её рассматривают и стайлгайды GitHub, и Google), но не вся картина. Документация живёт и в:

• Комментариях в коде
• Диаграммах архитектуры
• Справочниках API
• Руководствах по устранению неполадок
• Списках изменений и записях о дизайн-решениях

Каждый из этих элементов спасает кого-то (скорее всего, вас в будущем) от необходимости восстанавливать ход мыслей с нуля.

Главные выводы

• Документация пишется для людей, а не для компьютеров.
• Ваше будущее «я» — обычно первый читатель.
• Небольшие заметки, написанные регулярно, лучше одного гигантского документа в конце.
• Хороший README формирует первое впечатление и создаёт доверие до того, как кто-то прочитает ваш код.
• Документация — часть разработки, а не то, что делается после.

В следующий раз, когда закончите писать код, спросите себя не только «Готово ли?», но и «Сможет ли кто-то другой разобраться, как это использовать?»

Если ответ «нет» — ваша следующая строчка должна быть не кодом, а документацией.