Представьте, что в рецепте для приготовления еды была бы вводная часть о том, откуда привезли продукты, как их упаковывали и доставляли.  Вы бы стали читать рецепт из 10 страниц, чтобы приготовить салат? Что-то я сомневаюсь. Схожая ситуация бывает в документации, когда она пишется без шаблона по принципу "чем больше, тем лучше". Если ваши  документы не читают, не понимают, или вы не знаете с чего начать описывать интеграцию,  то эта статья для вас.  Я тех. лид системных аналитиков и прошла долгий путь к шаблонам документации в разных компаниях. Чаще всего у системного аналитика болит от того, что его техническое задание (ТЗ) не читают. Разрабатывают как поняли, тестируют как услышали, а заказчик ждет вообще другое. Еще болит, а как описать задание разработчику, если в компании нет шаблона? Самое важное понять, кто и для чего будет пользоваться документацией.  Аналитик думает, что документы нужны всем, а остальные уверены, что им они не нужны. Поэтому для составления удачного шаблона нужно понять, что мотивирует вашу команду прочитать документацию. Перед нами команда, которая разрабатывает новые интеграции. Отвечает за документацию Ставит задачи аналитику Программирует Проверяет, правильно ли сделал разработчик Задача аналитика  - описать интеграцию систем (спроектировать API). В описании ищет ответы на вопросы: Зачем нужна новая интеграция бизнесу?Что пользователи получат в результате разработки? Без документа не понимает как ему делать задачу, поэтому вопросы у него такие: Что мне делать: параметры запроса-ответа?В какие системы сходить за данными или передать? Прочитав описание интеграции, сможет ответить на вопросы: Как бы это все сломать: какие ошибки можно сделать?Где найти тестовые запрос-ответ?С какими системами есть взаимодействие, чтобы проверить весь путь? Этому человеку нужна любая документация, потому что у него один вопрос: Как переиспользовать или доработать сервис, чтобы ничего не сломать? Скорость разработки - это важное преимущество, потому что кто первый вышел на рынок с продуктом, тот и выиграл. Время на написание или чтение ТЗ выделяется мало, поэтому документ должен содержать необходимый и достаточный минимум для быстрой разработки. В шаблоне на интеграцию (API) будут разделы: Почему именно такая структура?  Спокойствие, только спокойствие, сейчас все расскажу!  Вспомните, у каждого участника команды были вопросы, мотивирующие его прочитать документацию. От них и отталкиваемся, поэтому такое содержание. В разделе можно найти ответы на вопросы: Зачем нужна новая интеграция бизнесу?Что пользователи получат в результате разработки? В этих разделах документа есть информация: Что мне делать: параметры запроса-ответа?Где найти тестовые запрос-ответ?Как бы это все сломать: какие ошибки можно сделать? Здесь есть ответы на вопросы: В какие системы сходить за данными или передать?С какими системами есть взаимодействие, чтобы проверить весь путь?Как переиспользовать или доработать сервис, чтобы ничего не сломать? Аналитическая задача  - описать интеграцию, которая позволить добавить информацию о животном на сайте. Аналитик понимает, что нужен сервис для работы с данными о животных и метод, который создаст запись (прим. в статье не описано почему именно такой метод спроектирован, потому что статья направлена именно на шаблон описания). В шаблоне есть: Раздел содержит таблицу, которая позволяет понять, о чем будет документ, и найти все ссылки в одном месте. Автор - ФИО, кто пишет или правит документЗадача - ссылка на задачу (например, JIRA) или описание задачиБизнес постановка - описание какую пользу приносит эта задача пользователямСвязанные документы - документы или ссылки с описанием, что в них находится Раздел содержит таблицу: Версия - номер версииДата - дата в формате ДД.ММ.ГГГАвтор - ФИО кто создал или изменил документОписание изменений - текстовое описание того, что вы добавили в документ.  Пример запроса и ответа для добавления информации о животном на сайте  Раздел содержит таблицу: Параметр - название параметра на английскомТип данных - указать тип данных параметра с ограничениями по длине если они естьОбязательность - да/нетОписание - понятное описание для чего используется параметрВарианты значений - перечислить варианты значений с пояснениями, для чего они используются или привести пример одного из значений Раздел содержит таблицу: Параметр - название параметра на английскомПроверка - условие и результат проверки  Параметры аналогичны входным  Для построения сервиса использовался инструмент plantuml. Работа с ним описана в статье https://habr.com/ru/post/661931/ Посмотреть реализованный сервис можно по ссылке https://petstore.swagger.io/#/pet/addPet. Для удобства описания были придуманы некоторые проверки и коды ошибок :) В разделе описываются сервисы, которые вызываются из выше описанного метода. Формат описания также будет содержать запрос и ответ, входные и выходные параметры. Например, если бы метод POST /pet пошел бы в следующую систему для сохранения информации о животном. Вы получили шаблон технической документации на API . Скачать шаблон google docs можно по ссылке Его можно адаптировать под потребности людей, которые читают ваши документы. Документ может быть удобен вам, но разработчик, тестировщик и другие ребятам из команды не найдут ответы на свои вопросы. Поэтому хорошей практикой будет систематический сбор обратной связи от вашей команды, а все ли им удобно и понятно в документе. Возможно вам шаблон не подойдет, но вы всегда можете составить свой и поделиться им в комментариях.  Solution архитектор