Инженерия ПО
Документирование и ADR
Новый инженер в команде. Странное архитектурное решение. Почему MongoDB для финансовых данных? Кто принял это решение? Без ADR - никто не знает, оригинальная команда ушла. Anthropic публикует свои core views в открытых документах. Stripe публикует API principles. Google хранит 'Design docs' для всех major систем. Документация - это не бюрократия, это institutional memory без которой каждая команда изобретает одни и те же колёса.
- **Rust RFC процесс**: каждое изменение языка проходит через публичный RFC. Тысячи комментариев от сообщества. Решения документированы навсегда - понятно почему язык такой
- **Google Design Docs**: перед крупным engineering проектом пишется design doc. Обсуждается командой. Потом хранится как исторический артефакт. Golang, Kubernetes - всё началось с design docs
- **Stripe API Reference**: полностью генерируется из OpenAPI spec. Всегда актуальна, поддерживает несколько версий, интерактивные примеры. Эталон API документации в индустрии
Architecture Decision Records
Architecture Decision Record (ADR) - короткий текстовый документ фиксирующий важное архитектурное решение с его контекстом. Концепция Michael Nygard (2011). Хранится в git репозитории рядом с кодом (docs/adr/0001-use-postgresql.md). Никогда не изменяется: если решение изменилось - создаётся новый ADR со статусом 'Supersedes ADR-001'. Это сохраняет полную историю принятых решений.
ADR решает проблему institutional memory: разработчик приходит в проект через год и видит странное решение - почему PostgreSQL вместо MongoDB? Без ADR - никто не помнит, исходные авторы ушли, документация устарела. С ADR - открыть docs/adr/0003-postgresql-over-mongodb.md и прочитать весь контекст: рассмотренные альтернативы, trade-offs, кто принял решение и когда. Жить с решением через 2 года проще когда понимаешь почему оно было принято.
ADR принятый год назад стал неактуальным: команда решила перейти с REST на gRPC. Что сделать со старым ADR?
RFC процесс
RFC (Request for Comments) - процесс асинхронного обсуждения и принятия крупных технических изменений. Rust lang, Python, Django используют RFC процесс для language evolution. В engineering командах: любой может предложить RFC, команда асинхронно комментирует (GitHub PR, Notion), через 1-2 недели решение принимается (автор или TL). Альтернатива длинным синхронным митингам.
RFC формат: Problem Statement (что именно не работает или что нужно улучшить), Proposed Solution (конкретное предложение), Alternatives Considered (другие варианты которые рассматривались), Trade-offs (плюсы и минусы предложения), Implementation Plan (как реализовать, milestone). Пустые альтернативы ('мы рассмотрели ничего не делать') снижают качество - нужны реальные варианты с реальным анализом.
RFC предлагает перейти на новый framework. Раздел 'Alternatives Considered' пустой - автор не рассматривал другие варианты. Что это означает для качества RFC?
Wiki и знания команды
Знания команды хранятся в нескольких местах с разным lifetime: Slack (ephemeral - исчезает через месяцы), Email (личный - недоступен при уходе человека), Wiki (полуперманентный - живёт но устаревает), Код (постоянный - актуален пока работает). Проблема wiki: документация устаревает быстрее чем её обновляют. 'Documentation rot' - wiki написана в 2020 году, описывает систему которой больше нет.
Принцип 'дорогой wiki': документировать только то, что имеет долгий срок жизни и высокую ценность для команды. Onboarding guide (обновляется редко, ценность высокая), system architecture overview, runbooks для production incidents, API договоры с внешними командами. Не документировать: детали реализации которые меняются (лучше в коде), процессы которые постоянно меняются (лучше в Slack/Notion), технические факты которые есть в документации инструментов.
Onboarding wiki написана год назад. Новый инженер жалуется что половина инструкций не работает. Лучший ответ?
Documentation as Code
Documentation as Code (DoC) - хранение документации рядом с кодом в том же репозитории, в git. Преимущества: документация версионирована (git history), изменения кода + документации в одном PR (reviewer видит оба), CI проверяет документацию (broken links, сломанные примеры кода), документация актуальна для конкретного релиза (git tag). Инструменты: MkDocs, Docusaurus, mdBook, Sphinx.
OpenAPI (Swagger) - specification-first API documentation. Описывается YAML/JSON схема API, из неё автоматически генерируется: интерактивная документация (Swagger UI), клиентский код (openapi-generator), тесты (contract testing). Если API изменился без изменения spec - CI падает. Docs-as-Code для API: spec в git, генерация при каждом build. Stripe, Twilio, GitHub - все генерируют документацию из OpenAPI.
Хорошая документация это объёмная документация - чем больше написано, тем лучше
Лучшая документация - минимально необходимая но актуальная. Устаревшая документация хуже её отсутствия - вводит в заблуждение. Фокус на высокой ценности с долгим сроком жизни
Documentation rot: каждая строка документации требует поддержки. Больше документации = больше времени на поддержку актуальности. Принцип: документировать 'почему', код объясняет 'что'
Разработчик изменил API endpoint (добавил обязательное поле в request). Документация в Confluence не обновлена. Партнёрская команда использует старую документацию. Как Documentation as Code предотвратил бы это?
Связанные темы
Документирование связано с процессами принятия решений и лидерства:
- Техническое лидерство — ADR и RFC - основные инструменты TL для документирования решений и создания прозрачного процесса принятия решений
- API Design: REST, GraphQL, gRPC — OpenAPI спецификация - Documentation as Code для API: spec является первичным артефактом из которого генерируется документация и клиентский код
Вопросы для размышления
- Как создать культуру обновления документации в команде где все заняты и документация всегда на последнем месте?
- ADR и RFC - в чём разница и когда использовать каждый из них?
- Как измерить качество документации команды - какие метрики показывают что документация работает?