209. Что такое документация, зачем она нужна и как ее писать

Коллега руководитель проекта спросил, как правильно писать документацию. Хочу поделиться своим ответом, возможно вам будет полезно.

Для начала определим, что документация – это любое описание «как это должно работать». Когда вы читаете инструкцию к пылесосу – это документация. И когда пишете программисту, как должен работать нарисованный вами лендинг, это тоже документация.

Некоторые коллеги ошибочно полагают, что форма документации – это главное. И отчаянно спорят, что лучше: текстовое описание в wiki или графический mindmap, или таблица, или видео ролик. Кто-то считает, что документация вообще не нужна и проще все на словах объяснить. Форма не важна. Главная цель в другом:

Документация должна приносить больше пользы, чем потрачено сил на ее создание.

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

Главное, чтобы программист смог его прочитать и осознать. И тут кроется второй важный принцип:

Форма и подробность документации должна подходить для её читателей.

Я раньше писал подробные технические задания, где описывал как реализовать ту или иную фичу продукта. Программисты читали, делали по ТЗ, а потом выяснялось, что половину забыли. Для них было слишком «много букв».

Тогда я стал делать ТЗ короче, но добавил чеклисты «что нужно сделать». Названия чеклистов соответствовали подзаголовкам текстового задания. Количество пропущенных логических кусков снизилось почти до нуля.

Я предпочитаю давать задание одновременно в разных формах, которые дополняют друг друга. Для front-end задач используем: Макет в Фигме с разными состояниями + устное обсуждение + чеклист. Для back-end задач: Техническое задание в виде текста + устное обсуждение + чеклист.

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

Документация должна быть краткой и в удобной для поддержания форме.

Когда у нас выходит на работу новый сотрудник, он получает личную Trello доску с перечнем задач на первый день, первую неделю и первый месяц. Это гарантия, что мы не забудем рассказать новичку что-нибудь важное. Такую документацию легко поддерживать, при необходимости я за минуту добавляю новую карточку в шаблон Trello доски.

По этой причине наши UX/UI-дизайнеры не тратят месяцы на составление персон пользователей, которые потом годами пылятся без дела. Они используют чеклисты, описывающие, что именно должен сделать тот или иной пользователь. По этим чеклистам они проверяют свои интерфейсы на полноту. Пункты чеклистов короткие, например: «Установить апгрейд модуля». Такие проверочные списки легко поддерживать в актуальном состоянии. Да, они не содержат полного описания, но оно здесь и не требуется.

Итак, хорошая документация должна:

1. Приносить больше пользы, чем проблем.
2. Иметь удобную для читателей форму или несколько форм.
3. Быть простой и удобной для поддержки.