За всё время удалось поработать на проектах с разным уровнем документации. От полного её отсутствия до удушающего бесполезного объёма.
И каждый раз, приходя на новый проект, задаёшься вопросом:
Какой объём минимально эффективен, чтобы давать максимальную пользу?
Правильного ответа я ещё не нашёл, но вот что удалось понять:
🔸Переизбыток и недостаток одинаково плохи
Кажется очевидным, что мало документации — плохо. Но переизбыток — не менее разрушителен.
В одном случае до 40% времени уходит на написание и поддержку. В другом — до 20% тратится на поиск информации, которую никто не зафиксировал. Оба варианта одинаково воруют время — просто с разных сторон.
🔸Детальная документация внутрянки чаще всего не нужна
Хочется чтобы все понимали, как работает тот шедевр, что ты создал. Но... и как часто ты сам это читал второй раз?
Отличное решение — максимально короткий Guide, который объяснит как пользоваться.
В детали каждый погрузится сам — AI в этом отлично помогает.
На последних местах работы отлично себя зарекомендовали зарисовки в paint с комментариями (смотри скрин).
🔸Чем дальше документы друг от друга — тем сложнее искать информацию
Тут прямо как с cohesion и coupling. Для документации это тоже работает: держи документы, объединённые одной тематикой, рядом друг с другом.
А связи с другими темами упоминай в головном файле.
Головной документ я всегда использую для хранения полезных ссылок, которые важно держать рядом.
Например, при проектировании сервиса чата, в головном файле "Чат" было оглавление и полезные ссылки:
Cтарые GDD-файлы
Задачи
Доски в Figma/Miro
Ссылки на репозитории
В общем всё, до чего нужно часто и быстро дотянуться.
🔸Хочется написать красиво — пиши на Хабр
А в документах ключевое — экономия ресурсов и времени читателя.
У меня благо есть блог и любимая жена-филолог
, которые учат писать экономично.Но поначалу, читая только Хабр, книги и блоги, я старался копировать способ повествования в документацию.
В итоге это только моё эго тешило — коллеги документ не читали, потому что на полстраницы воды приходилось одно полезное предложение.
Документ — не статья. Здесь важна плотность информации: короткие предложения, списки, заголовки.
Читатель пришёл за ответом, а не за историей.
🔸Навигация и разметка важны
Это опять же про экономию времени другого человека. Текст без разметки ощущается громоздким — его тупо лень читать.
Даже в статьях этого блога, где лимит 4096 символов, я использую emoji, цитаты, ссылки и выделения — иначе стена текста убивает внимание.
В документации это ещё критичнее. Человек приходит не читать, а искать. Оглавление, заголовки, списки — это не украшение, а навигация.
Без них даже полезный документ превращается в текст, который проще спросить у коллеги, чем найти в нём ответ.
🔹Что важно документировать
Кропотливо собранный список важных разделов и документов:
|— Фича / система / модуль / домен
|— Продуктовые требования — метрики, бизнес, влияние на аудиторию, сроки, список фичей
|— GDD — описание фичей от дизайнеров
|— Техническая документация:
|— Архитектура: C4 system, container, sequence diagram, ADR
|— Требования: из чего должны состоять container'ы и component'ы
|— How to: короткие Guide'ы как быстро решить проблему
|— Исследования: результаты поиска решений, используются для обоснования
Самым жирным, как правило, будет раздел How to. Документы в него рекомендую добавлять каждый раз, как кто-то задаёт вопрос.
Для ориентира — пример документации в FastMigrations.Json. Не раз отмечалась опытными разработчиками как хороший пример.
🔻 Документация — это не про объём, а про доступность нужной информации в нужный момент. Минимум текста, максимум структуры — и команда перестаёт тратить время на поиск того, что уже кто-то знает.
А что ещё из важного ты документируешь на своих проектах? Что из перечисленного тебе пригодилось или чего не хватает?
Ты знаешь кому переслать эту статью 💪
#проект_в_разработке@UniArchitect
