Меры по обеспечению качества, типы документации
Этот материал объясняет документацию как инструмент контроля качества, включая контрольные вопросы и теги.
В двух словах
Документация делает требования, поведение и свидетельства проверяемыми. Основные артефакты: документация пользователя, документация интерфейсов, документация программы, документация сетевой архитектуры, отчёты тестирования и чек-листы — все с чёткими целями, структурой, ответственными лицами и процессом поддержки.
Краткое описание
Документация пользователя
Адресована конечным пользователям и операторам: задачи, последовательность действий, сценарии ошибок, способы получения поддержки. Цель: самостоятельное решение проблем, снижение нагрузки на support.
Документация интерфейсов
Определяет контракты: endpoints, схемы данных, коды ошибок, authentication, управление версиями. Основа для интеграции и contract-тестирования.
Документация программы
Сосредоточена на поддерживаемости реализации: обзор архитектуры, модули, публичные интерфейсы, инварианты, комментарии в коде, инструкции сборки и запуска.
Документация сетевой архитектуры
Описывает топологию, зоны, порты, протоколы, потоки, средства контроля безопасности. Основа для защиты и анализа сбоев.
Отчёты тестирования
Подтверждают эффективность тестов: связь с тестовым планом, описание окружения, наборы тестов, результаты, дефекты, решение о выпуске.
Чек-листы
Стандартизируют повторяющиеся проверки (review pull requests, запуск в production, адаптация новых сотрудников). Предотвращают упущения.
Для аттестации AP2 важна проверяемая связь: требование → свидетельство → результат, связанные через tickets, commits, builds, releases.
Контрольные пункты для аттестации
- Целевая аудитория и назначение документа определены однозначно
- Версионирование, отслеживание изменений, ответственные лица, цикл review
- Минимальный набор содержания для каждого типа (используйте шаблоны структуры)
- Функция доказательства (приёмка, аудит, поддержка, эксплуатация)
- Качество: актуальное, полное, недвусмысленное, проверяемое, понятное
- Связь с контролем качества (требование ↔ тестовый случай ↔ результат ↔ дефект ↔ выпуск)
- Инструменты: wiki, репозитории Markdown, диаграммы как код, связи между задачами
- Релевантность для IHK: показать, что документация поддерживается, версионируется, связана и интегрирована в процесс
Основные компоненты
- Документация пользователя (целевая аудитория, задачи, инструкции, примеры, справка по ошибкам, контакты support)
- Документация интерфейсов (назначение, endpoints, методы, схемы, коды ошибок, authentication, версионирование)
- Документация программы (архитектура, модули, публичные интерфейсы, модели данных, инварианты, сборка/запуск)
- Документация сетевой архитектуры (топология, IP-диапазоны, зоны, порты/протоколы, правила firewall, потоки, высокая доступность)
- Отчёт тестирования (связь с тестовым планом, окружение, тестовые случаи, фактические результаты, дефекты, решение о выпуске)
- Чек-лист (назначение, проверяемые пункты, свидетельства, ответственные, дата, результат, отклонения)
- Управление документацией (владелец, цикл review, журнал изменений, уровни одобрения)
- Хранилище (единственный источник истины, права доступа, поиск, версионирование в репозитории)
- Качество (проверка читаемости, проверка консистентности, отслеживание актуальности, проверка ссылок)
- Соответствие стандартам (связь с ISO 25010, защита данных, безопасность, эксплуатация)
Пример из практики (API корзины товаров + портал администратора)
Документация пользователя:
- Целевая аудитория: операторы, администраторы
- Задачи: оформление заказа, создание кредит-ноты
- Последовательность действий: запуск → вход → поиск клиента → добавление товара → проверка скидки → завершение заказа
- Справка по ошибкам: частые сообщения об ошибках с решениями
- Поддержка: время работы, процесс создания заявок
Документация интерфейсов:
- OpenAPI: POST /api/orders, GET /api/orders/{id}
- Схемы: Order, Position (ограничения)
- Ошибки: 400 валидация, 401 authentication, 409 конфликт
- Authentication: OAuth2, scopes order:write, order:read
- Версионирование: Accept: application/vnd.shop.v1+json + план deprecation
Документация программы:
- Архитектура: многоуровневая, Controller → Service → Repository, Ports & Adapter
- Ключевые классы: OrderService, инвариант: сумма ≥ 0
- Конфигурация: профили, secrets через Vault
- Сборка: инструменты, команды запуска, логирование, tracing
Документация сетевой архитектуры:
- Зоны: интернет → DMZ → приложение → база данных
- Потоки: браузер → портал (TLS 443) → API (TLS 443) → БД (5432)
- Firewall: основные разрешения, точки мониторинга
- Высокая доступность: reverse proxy, 2 экземпляра, репликация БД
Отчёт тестирования:
- Ссылка на тестовый план: TP-007, окружение: Staging-23
- Случаи: заказ с дисконтом, граничные значения, пути ошибок
- Результат: пройден, пройден, не пройден → дефект ID 532
- Одобрение: подтверждение product owner, дата, подпись
Чек-листы:
- Review pull request: архитектура, безопасность, тесты, документация обновлена
- Запуск в production: мониторинг активен, runbooks полные, rollback подготовлен, feature flags готовы
Преимущества и недостатки
Преимущества
- Прозрачность, возможность приёмки
- Быстрая адаптация новых сотрудников
- Снижение затрат на эксплуатацию и поддержку
- Возможность аудита
Недостатки
- Затраты на поддержку документации
- Риск устаревания информации
- Требует дисциплины и ответственности
Типичные контрольные вопросы (с кратким ответом)
- Какова цель документации интерфейсов в контроле качества? Определяет проверяемые контракты, позволяет писать contract-тесты, предотвращает ошибки интеграции.
- Что обязательно должно быть в документации пользователя? Целевые аудитории, задачи, последовательность действий, примеры, справка по ошибкам, способы получения поддержки, информация о версии.
- Как документация программы помогает поддерживаемости? Описывает архитектуру, модули, публичные интерфейсы, инварианты, что снижает время адаптации и затраты на изменения.
- Что должен содержать отчёт тестирования? Связь с тестовым планом, описание окружения, тестовые случаи, фактические результаты, обнаруженные дефекты, решение о выпуске, дата и ответственные.
- Когда полезны чек-листы? Для повторяющихся операций с рисками (review pull requests, запуск в production, адаптация новых сотрудников).
Ключевые источники
- https://iso25000.com
- https://www.w3.org/TR/using-aria (для семантической документации UI)
- https://plantuml.com