Как организовано написание документации

Что проверяют

Есть ли у вас рабочий процесс, при котором документация не отстаёт от кода, или всё держится на «спросите у автора». Следом обычно спрашивают, как вы добиваетесь, чтобы её реально обновляли, и что задокументировали сами. Этот же вопрос полезно задать работодателю: по ответу видно, как быстро вы войдёте в проект.

Как отвечать

Разложите документацию фронтенда по уровням и назовите инструмент для каждого:

• запуск проекта: README в корне и в каждом пакете монорепозитория. Как поставить зависимости, какие нужны переменные окружения, как запустить тесты. Критерий простой: новичок поднимает проект без вопросов в чат;
• компоненты: Storybook, где у каждого компонента истории на все состояния, а таблица пропсов собирается из типов TypeScript. Истории заодно служат тестами, визуальными или тестами взаимодействия;
• код и API: TSDoc на публичных функциях и хуках, из них при желании собирается сайт через TypeDoc. Типы бэкенд-API лучше генерировать из OpenAPI-схемы, тогда описание контракта не расходится с кодом;
• решения: ADR, короткие записи в репозитории о том, почему выбрали, скажем, TanStack Query, а не свой кэш, и какие варианты отбросили;
• продуктовое: Confluence или аналог для требований и процессов, туда из кода ссылаются, а не копируют.

Главное в ответе не инструменты, а правило актуальности: документация меняется в том же пул-реквесте, что и код, в шаблоне PR есть пункт про неё, ревьюер его проверяет. Документы в репозитории (docs-as-code) живут дольше вики именно потому, что проходят ревью.

Добавьте свой пример с цифрами: что задокументировали и что изменилось, например сколько занимал онбординг до и после. Если в прошлой команде процесса не было, скажите честно и опишите, с чего бы начали.

Где спотыкаются

Говорят «код самодокументируемый». Хорошие имена объясняют, что делает функция, но не почему выбрано такое решение и как поднять проект.

Перечисляют Confluence, Notion и Storybook без процесса. Интервьюера интересует, кто и когда обновляет документы, а не где они лежат.

Приводят пример «написал документацию, всем стало удобнее» без деталей. Без конкретики это звучит как заготовка.