UAEN

Снизить расходы, стать технически независимыми!

Создаём техническую документацию для ваших сложных веб-сайтов (веб-систем, веб-инструментов). Профессиональное описание: backend, frontend, API и бизнес-логика.

Зачем нужна техническая проектная документация для сложных проектов?

Короткий ответ: «Чтобы бизнес экономил деньги и время и обеспечил независимость от одной команды!»

В процессе развития веб-проекта накапливается много технической и продуктовой информации. Часть хранится в коде, часть — в различных сервисах, а часть остаётся только в опыте отдельных специалистов, команды, а если повезёт, и компании.

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

Что это даёт клиенту:

1. Экономия времени и денег бизнеса
Структурированная документация сокращает время на поиск информации и изучение проекта, помогая уменьшить расходы на его поддержку и развитие.

2. Более быстрый онбординг
Новые специалисты быстрее знакомятся с архитектурой, функционалом, модулями и основными процессами проекта.

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

4. Прозрачность проекта
Архитектура, бизнес-логика, интеграции и правила работы системы описаны структурированно и доступны команде.

5. Более безопасные изменения
Понимание структуры и взаимосвязей системы помогает снизить риск ошибок при доработках.

Что мы документируем

Документация охватывает ключевые части веб-проекта.
Набор документации формируется в зависимости от специфики и функционала конкретного проекта.

Создание технической документации для Backend / Laravel

  • Архитектура и структура
    Описываем архитектуру системы, структуру проекта, основные модули, компоненты и принципы организации кода.

  • API
    Документируем endpoint-ы, HTTP-методы, примеры запросов и ответов, авторизацию, ошибки и версионирование API.

  • База данных
    Фиксируем структуру таблиц, поля, типы данных, связи, индексы и правила работы с миграциями.

  • Внешние интеграции
    Описываем сторонние сервисы, принципы взаимодействия с ними, форматы данных, обработку ошибок и необходимые конфигурации.

  • Фоновые процессы и кеширование
    Документируем очереди, Jobs, политики повторных попыток (retry), кеширование, TTL и правила инвалидации.

  • Развёртывание, мониторинг и безопасность
    Описываем развёртывание, CI/CD, логирование, мониторинг, управление доступом и защиту конфиденциальных данных.

Создание технической документации для Frontend / Vue 3

  • Архитектура frontend
    Описываем структуру проекта, компоненты, views, store, composables, router, services и assets.

  • Компоненты и UI
    Фиксируем принципы построения Base, Reusable и Page components, а также правила их повторного использования.

  • State management и работа с данными
    Документируем Pinia stores, локальные состояния, работу с API и хранение данных.

  • Маршрутизация
    Описываем структуру router, динамические маршруты, route guards и принципы добавления новых страниц.

  • Тестирование и оптимизация
    Фиксируем структуру тестов, способы их запуска, lazy loading, кеширование запросов и другие подходы к оптимизации.

Создание технической документации для Product / Manager Documentation

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

  • Бизнес-процессы
    Фиксируем ключевые процессы, пользовательские сценарии, роли и правила работы системы, чтобы менеджерам и заказчику было проще понимать логику продукта.

  • Интеграции
    Описываем основные сторонние сервисы, их назначение и роль в работе проекта.

  • Инструкции по работе с системой
    Создаём пошаговые инструкции по работе с админ-панелью, обновлению контента и выполнению других типовых операций. При необходимости добавляем скриншоты, текстовые материалы или видеоинструкции.

  • Команда и ответственные
    Фиксируем информацию об участниках проекта и специалистах, ответственных за его основные части: PM, backend, frontend, QA и других.

  • Основные изменения и обновления
    Описываем важные функциональные изменения и обновления, произошедшие в процессе разработки проекта.

Как формируется документация

01 Этап

Анализ проекта

Изучаем структуру, функциональность и ключевые составляющие системы.

02 Этап

Формирование структуры

Определяем, какие разделы документации нужны именно для этого проекта.

03 Этап

Документирование

Фиксируем архитектуру, backend, frontend, API, бизнес-логику, интеграции и другие необходимые компоненты.

04 Этап

Структурирование материалов

Объединяем информацию в логичную систему, которой удобно пользоваться команде.

05 Этап

Передача документации

Размещаем документацию в согласованной среде, чтобы команда могла использовать её как базу знаний для дальнейшей работы над проектом.

Инструменты

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

  • GitHub Wiki / GitLab Wiki — для структурированного хранения документации проекта и работы с текстовыми материалами.
  • SwaggerHub — для API-документации, описания endpoint-ов, запросов и ответов.

FAQ

  • 01

    Можно ли создать документацию для уже существующего проекта?

    Да, документацию можно создать для проекта, который уже находится в разработке или на поддержке. Конкретный объём работ зависит от состояния проекта и информации, которую необходимо зафиксировать.
  • 02

    Документируется ли только backend?

    Нет. Документация может охватывать backend, frontend, API, базу данных, интеграции, бизнес-логику, DevOps, тестирование и другие составляющие проекта.
  • 03

    Можно ли документировать frontend на Vue 3?

    Да. Документация frontend может охватывать архитектуру Vue 3, компоненты, маршрутизацию, работу с API, UI/UX, тестирование, оптимизацию и deployment.
  • 04

    Входит ли API-документация?

    Да, API — отдельное направление документации. Она может содержать endpoint-ы, HTTP-методы, примеры запросов и ответов, коды ошибок, авторизацию и версионирование API.
  • 05

    Нужно ли документировать весь проект?

    Не обязательно. Набор разделов формируется в зависимости от специфики, архитектуры и функционала конкретного проекта.
  • 06

    Подходит ли документация для передачи проекта другой команде?

    Да. Одна из ключевых целей документации — сделать знания о проекте структурированными и доступными для новых специалистов и команд.
  • 07

    Где хранится документация?

    В зависимости от проекта и выбранного подхода документация может храниться в Wiki-среде, а API — в специализированном инструменте для API-документации.
  • 08

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

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