Документация — итоги года

23 января 2023 · Дмитрий Орлов · 11 мин чтения

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

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

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

Командная работа

За год проект вырос, но принципы остались прежними. Главная сложность оказалась не в коде, а в договорённостях внутри команды. Мы используем открытые форматы, чтобы данные можно было забрать в любой момент. Мы стараемся писать так, чтобы через год код было легко читать. Первые отзывы были осторожными, но уже через месяц картина изменилась. Оказалось, что половина времени уходит на согласование мелочей.

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

Хороший макет начинается с текста, а не с картинок. Мы перенесли сборку на отдельный сервер, и релизы стали спокойнее. Проще всего начать с примера и менять его под свою задачу. Важно заранее договориться, какие метрики считать успехом.