Виды

• Технические задания (спецификации) 

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

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

представляет архитектуру и дизайн-решения, включая диаграммы и схемы, описания и характер взаимодействия компонентов, а также другие технические аспекты решения.

• Пользовательская документация 

содержит информацию по эксплуатации продукта, в том числе по установке, настройке, запуску, использованию, резервному копированию, отладке, описанию интерфейсов и т. д.

• Тестовая документация 

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

• Документация по безопасности 

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

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

• Точность.

Фактическая достоверность и актуальность информации, отсутствие ошибок.

• Ясность

Четкая структура, простой стиль изложения, лаконичность. Полезные инструкции, понятные примеры, наглядные графические материалы.

• Полнота

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

• Согласованность

Стиль, тон, терминология и оформление — всё должно согласовываться в рамках материала и соответствовать назначению документа.

• Удобство использования

Предельно ясная организация материалов, качественная навигация, возможность сквозного поиска по документам.

• Релевантность

Максимальное соответствие запросам заинтересованных сторон, ответы на поставленные вопросы, помощь в решении проблем.

• Технологичность

Простота сопровождения и обновления.

Для чего нужна документация

• Обеспечение коммуникации. 

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

• Обмен знаниями. 

Фиксирует знания и позволяет обмениваться ими как внутри проектной команды, так и за ее пределами. Зачастую выступает отправной точкой для дальнейшего развития и помогает при сопровождении решений.

• Обеспечение соответствия требованиям.

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

• Обеспечение качества.

Позволяет разрабатывать продукт в соответствии с установленными стандартами качества.

• Управление рисками.

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

Структура документов

RFC

1. Глоссарий

2. Цель

3. Решаемые проблемы

4. Сроки, зависимости, риски

5. Предложения по дальнейшему развитию (опционально)

6. Функциональные требования (в формате User Story)

7. Нефункциональные требования

8. Артефакты системного дизайна:

   1. Модель С4
   2. ER и sequence диаграммы
   3. BPMN

Описание backend

1. Общее описание (+ sequence диаграмма);

2. Описание методов (или ссылка на Swagger или OpenApi):

   1. входящие данные (с примером),
   2. исходящие данные (с примером),
   3. алгоритм работы,
   4. список ошибок.

3. Описание базы данных (если несколько таблиц - с ER диаграммой):

   1. наименование поля,
   2. тип поля,
   3. краткое описание.

4. Нефункциональные требования.

Описание frontend

1. Дизайн

2. Схема переходов

3. Описание процесса

4. Для каждого экрана:

   1. Макет,
   2. Элементы экрана:
      1. Логика заполнения элемента,
      2. Логика при взаимодействии с элементом,
      3. Требования к отображению элемента.