Где велась документация на последней работе?

Система ведения документации в Android-разработке

На последнем месте работы документация велась в виде многослойной экосистемы, разделенной по типам информации и целевой аудитории. Это не был единый инструмент, а комплекс решений, адаптированных под конкретные задачи.

1. Основные платформы и их назначение

• Confluence / Notion (как альтернатива) — центральный хаб для высокоуровневой документации:

    *   **Общее видение продукта:** Roadmap, принципы дизайна (Design Guidelines), глоссарий.
    *   **Архитектурные решения (ADR — Architecture Decision Record):** Здесь фиксировались ключевые решения, например, переход на **MVVM** с **Clean Architecture**, выбор **библиотеки навигации (Jetpack Navigation или Decompose)**, стратегии кэширования. Каждая запись содержала контекст, варианты, принятое решение и последствия.
    *   **Процессы:** описание CI/CD пайплайнов (часто со ссылками на Jenkins/GitLab CI конфиги), процесс код-ревью, релиз-процедуры.
    *   **Онбординг:** подробное руководство для новых разработчиков по настройке среды, запуску проекта, ключевым модулям.

• Git (GitLab / GitHub) — документация в коде и рядом с ним:

    *   **README.md в корне репозитория:** Самое важное — быстрый старт. Содержал ссылки на все остальные ресурсы, инструкции по сборке, настройке окружения (Environment Variables), структуре проекта.
    *   **Документация в Pull Request (PR/MR):** Это была *живая* документация. Каждый нетривиальный PR сопровождался описанием:
        *   Контекста и проблемы (с ссылкой на задачу).
        *   Предложенного решения.
        *   Списком изменений.
        *   Скриншотами/видео (для UI изменений).
        *   Чек-листами для тестирования (QA Checklist).
        *   **Этот подход был невероятно ценным, так как документировал *эволюцию* кодовой базы.**

    *   **Код как документация (Code as Docs):** Чистые, понятные имена классов, методов, переменных. Активное использование **аннотаций KDoc (для Kotlin)** над сложными функциями, классами или неочевидными решениями. Генерация документации из KDoc с помощью **Dokka** для библиотечных модулей.

    ```kotlin
    /**
     * Репозиторий для работы с данными пользователя.
     * Реализует стратегию "Cache-Then-Network": сначала возвращаются кэшированные данные,
     * затем в фоне выполняется сетевой запрос для обновления.
     *
     * @param localDataSource источник кэшированных данных (Room)
     * @param remoteDataSource источник сетевых данных (Retrofit)
     * @param dispatcher корутин-диспетчер для выполнения фоновых операций (по умолчанию `Dispatchers.IO`)
     */
    class UserRepository(
        private val localDataSource: UserLocalDataSource,
        private val remoteDataSource: UserRemoteDataSource,
        private val dispatcher: CoroutineDispatcher = Dispatchers.IO
    ) {
        suspend fun getUser(userId: String): Flow<User> {
            // Реализация стратегии...
        }
    }
    ```

2. Документация API и дизайна

• Backend API: Использовался Swagger/OpenAPI. Спецификация в формате YAML/JSON хранилась в репозитории бэкенда, а для разработчиков фронтенда/Android генерировалась интерактивная документация через Swagger UI или ReDoc, развернутая на внутреннем сервере.
• Дизайн (UI/UX): Работа велась в Figma. Это был единый источник истины для всех экранов, компонентов, состояний, цветов, типографики. Плагины для Figma (например, Figma to XML) иногда использовались для ускорения верстки. Ссылки на макеты экранов обязательно добавлялись в задачи (Jira/YouTrack).

3. Принципы, которых мы придерживались

• «Документируй почему, а не что»: Код должен говорить сам за себя (что делается). Документация объясняет почему было принято то или иное решение, особенно если оно контринтуитивно.
• Близость к коду: Документация, которая устаревает первой, — та, которая далеко от кода. Поэтому ADR и README хранились в Git, а описание сложной бизнес-логики — в KDoc прямо над классом.
• Живые документы: Документация в Confluence/Notion регулярно пересматривалась и обновлялась, особенно разделы по онбордингу и архитектуре. За устаревание документации отвечала команда, ее создавшая.
• Минимум дублирования: Старались избегать копирования информации. Вместо этого использовались ссылки. Например, в Jira-задаче могла быть ссылка на ADR в Confluence, макет в Figma и спецификацию API в Swagger.

4. Процесс обновления

Документация обновлялась по мере необходимости. Любое значимое архитектурное изменение требовало создания или обновления ADR. Изменения в процессе сборки или настройке окружения сразу фиксировались в README.md. Это было частью Definition of Done (DoD) для многих задач.

Итог: Такой гибридный подход позволял эффективно работать и новичкам, и опытным членам команды. Ключевая документация (архитектурная, процессуальная) была централизована и доступна для поиска, а технические детали — максимально близки к коду, что снижало вероятность их устаревания. Главным вызовом было поддерживать дисциплину и культуру регулярного обновления этих ресурсов.