Как писать документацию по фичам и не бесить команду

Документация нужна, чтобы: ✅ другие разрабы не ломали голову, как работает новая фича ✅ новый человек в команде понимал, где и что делает фича ✅ бэкендеры, тестировщики и продакты спустя пару месяцев не гадали на кофейной гуще, о чем она и зачем

1. Коротко, о чем фича (TL;DR) Два предложения: что делает фича и зачем она вообще нужна.

Пример: «Добавляем автозаполнение адреса на странице заказа. Подключаем API Яндекс.Карт, чтобы люди не писали "мск, арбат, дом у Петровича"»

Или: «Ограничения на ввод символов (только латиница). Удаляем остальные, чтобы сохранить нервные окончания курьерских служб от ФИО محمد صلاح حامد محروس غالى»

2. Как фича выглядит (UI/UX) Картинка, макет из Figma или скриншот.

Описываем, как работает интерфейс: клики, анимации, что делать, если человек вводит ерунду.

Пример: «Пишет "Лени", а мы предлагаем "Ленинградский проспект" или "улица Ленина". Выбирает — подставляем в поле.»

3. Как оно работает (API и зависимости)

— Какие API дергаем? — Что приходит в ответе? — Какие методы используем? — Кешируем или нет?

Пример: GET /api/address?query=Москва,Арбат

Response: { "suggestions": [ { "address": "Арбат 12", "lat": 55.75, "lon": 37.6" } ] }

Если API вдруг умирает, просто оставляем ручной ввод

4. Что важно в коде (техническая реализация)

🔹 Где хранится состояние (Vuex, sessionStorage, у соседа)? 🔹 Как обновляются данные (сто первый watcher, хуки, молитвы)? 🔹 Какие ключевые функции отвечают за логику? 🔹 Какого фига не вынесли в отдельный компонент/модуль?

Пример: «Компонент AddressInput.vue подписывается на ввод, дергает API через debounce, обновляет suggestions. Если API не отвечает, показываем "Введите вручную"»

5. Что проверять (тестирование) 🔹 Где тест-кейсы? Скиньте ссылку на зефир. 🔹 Какие пограничные кейсы возможны? 🔹 Как ломается, если кто-то вводит китайские иероглифы?

Пример: ✅ Адрес подставляется корректно. ✅ Работает на медленном интернете (Throttle в DevTools). ⚠ Иногда API долго ничего не возвращает — возможно, нужен прелоадер.

6. Как это выкатывать и откатывать (поддержка, почините revert)

🔹 Какие данные записаны в хайлоды? 🔹 Где ссылка на мерж и как это откатывать, если все пошло не так?

Пример: «Фича выкатилась в МР (ссылка). Если API падает, ничего страшного – просто не будет подсказок. В крайнем случае, убираем страну из хайлодов — стабильный Гугл мапс поможет»

7. Как не потеряться в Confluence

📂 Раздел "Чекаут" → 📂 Новые фичи → 📄 "Автозаполнение адреса (2025)"

✅ В начале краткое описание. ✅ В конце ссылки на Jira, ключевые коммиты Gitlab, обсуждения, чтобы не бегать по чатам.

8. Как сделать так, чтобы документация не была кладбищем

🔹 Используем схемы (даже кривые, но понятные) и реперные точки кода. 🔹 Если фича изменилась – обнови плз доку, а не забей.

🎯 Вывод Пишем коротко, понятно и с примерами. Если через месяц сами не понимаем, что тут написано, значит документация дно, наймите аналитика

@leadWithout