Документация – это боль. Её не любят писать, её не любят читать, а когда она действительно нужна – её либо нет, либо она устарела.

Разработчики часто жалуются, что документация бесполезна, потому что: ❌ Она слишком длинная и запутанная. ❌ В ней куча воды и ненужной информации. ❌ Она устарела и не совпадает с реальностью.

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

Как же писать документацию, чтобы её читали и использовали? Разбираемся 👇

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

Перед тем как писать документ, ответьте на два вопроса: ✅ Кто его будет читать? Разработчики, тестировщики, аналитики, менеджеры? У каждого свой уровень знаний. ✅ Какую проблему он должен решить? Человек ищет конкретную информацию – не заставляйте его пробираться через километры текста.

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

📌 Пишите кратко и структурированноДокументация – это не художественная литература. Никто не хочет читать «простыню» текста, поэтому:

🔹 Пишите коротко. Чем короче и понятнее – тем лучше. 🔹 Разбивайте на блоки. Легче прочитать 5 абзацев, чем одно огромное полотно. 🔹 Добавляйте списки и таблицы. Это упрощает восприятие.

❌ Пример плохой документации: Наш API поддерживает несколько методов авторизации, таких как OAuth2, Basic Auth и API Key. Чтобы использовать OAuth2, вам нужно сначала зарегистрировать своё приложение в системе, получить client_id и client_secret, после чего запросить токен через endpoint /auth/token. Если у вас есть API Key, его можно передавать в заголовке Authorization.

✅ Хороший вариант: Методы авторизации: ✔️ OAuth2 – регистрация приложения → получение client_id и client_secret → запрос токена на /auth/token. ✔️ API Key – передача ключа в заголовке Authorization. Коротко, структурированно, легко найти нужную информацию.

📌 Кодовые примеры – обязательныРазработчики любят примеры. Лучше один раз показать, чем долго объяснять.

❌ Плохо: Чтобы получить список пользователей, сделайте GET-запрос на /users. В ответе будет JSON с полями id, name, email.

✅ Хорошо: GET /users Response: { "users": [ {"id": 1, "name": "Алиса", "email": "[email protected]"}, {"id": 2, "name": "Иван", "email": "[email protected]"} ] }

Пример сразу показывает, что делать и какой будет ответ. 📌 Удобная навигация и поискЕсли документацию сложно найти – её не читают.

Как сделать удобно? ✔️ Добавьте оглавление. Если документ длинный, сделайте кликабельные заголовки. ✔️ Делайте ссылки. Если в одном документе упоминается что-то из другого, ставьте ссылки. Простое правило: если нужную информацию нельзя найти за 30 секунд – документации как бы не существует.

📌 Поддерживайте документацию в актуальном состоянииСтарая документация хуже, чем отсутствие документации.

Как избежать устаревания? ✔️ Обновляйте документацию при каждом изменении кода. ✔️ Делайте ревью документации так же, как код-ревью. ✔️ Автоматизируйте, если возможно (например, документация API может генерироваться автоматически через swagger или аналоги).

Какая документация должна быть в проекте? Разные виды документации нужны для разных целей. Вот ключевые:

🔹 Техническая документация – архитектура, API, структуры данных. 🔹 Документация для разработчиков – как развернуть проект, описание кода, зависимости. 🔹 Документация для поддержки – что делать, если что-то сломалось. 🔹 Пользовательская документация – гайды для клиентов, если проект B2B.

Каждый документ должен быть коротким, понятным и легко доступным.

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