Представьте, что в рецепте для приготовления еды была бы вводная часть о том, откуда привезли продукты, как их упаковывали и доставляли.
Вы бы стали читать рецепт из 10 страниц, чтобы приготовить салат? Что-то я сомневаюсь. Схожая ситуация бывает в документации, когда она пишется без шаблона по принципу "чем больше, тем лучше".
![Рецепт салата Рецепт салата](https://habrastorage.org/getpro/habr/upload_files/dd2/01a/5d3/dd201a5d357ca954c761a4a035628793.jpg)
Если ваши документы не читают, не понимают, или вы не знаете с чего начать описывать интеграцию, то эта статья для вас.
Я тех. лид системных аналитиков и прошла долгий путь к шаблонам документации в разных компаниях.
С чего все начинается
Чаще всего у системного аналитика болит от того, что его техническое задание (ТЗ) не читают. Разрабатывают как поняли, тестируют как услышали, а заказчик ждет вообще другое. Еще болит, а как описать задание разработчику, если в компании нет шаблона?
Самое важное понять, кто и для чего будет пользоваться документацией.
Аналитик думает, что документы нужны всем, а остальные уверены, что им они не нужны. Поэтому для составления удачного шаблона нужно понять, что мотивирует вашу команду прочитать документацию.
Перед нами команда, которая разрабатывает новые интеграции.
![](https://habrastorage.org/getpro/habr/upload_files/a83/5d3/026/a835d3026eed789f5da30164bfa69dcb.png)
Системный аналитик
Отвечает за документацию
![](https://habrastorage.org/getpro/habr/upload_files/f96/e1e/646/f96e1e646ca437cc87c9210d77a2653a.png)
Product Owner
Ставит задачи аналитику
![](https://habrastorage.org/getpro/habr/upload_files/a0e/ea2/6f5/a0eea26f53a74c12a3ea63313365db72.png)
Разработчик
Программирует
![](https://habrastorage.org/getpro/habr/upload_files/a4b/27d/72f/a4b27d72fc35e611e844a4f4ac4cb7b4.png)
Тестировщик
Проверяет, правильно ли сделал разработчик
Задача аналитика - описать интеграцию систем (спроектировать API).
Для чего команде документ
Product owner
В описании ищет ответы на вопросы:
Зачем нужна новая интеграция бизнесу?
Что пользователи получат в результате разработки?
Разработчик
Без документа не понимает как ему делать задачу, поэтому вопросы у него такие:
Что мне делать: параметры запроса-ответа?
В какие системы сходить за данными или передать?
Тестировщик
Прочитав описание интеграции, сможет ответить на вопросы:
Как бы это все сломать: какие ошибки можно сделать?
Где найти тестовые запрос-ответ?
С какими системами есть взаимодействие, чтобы проверить весь путь?
Аналитик другой команды
Этому человеку нужна любая документация, потому что у него один вопрос:
Как переиспользовать или доработать сервис, чтобы ничего не сломать?
Скорость разработки - это важное преимущество, потому что кто первый вышел на рынок с продуктом, тот и выиграл. Время на написание или чтение ТЗ выделяется мало, поэтому документ должен содержать необходимый и достаточный минимум для быстрой разработки.
![Документы могут быть слишком подробными (слева), но выполнять задачу проще по-понятному (справа). Документы могут быть слишком подробными (слева), но выполнять задачу проще по-понятному (справа).](https://habrastorage.org/getpro/habr/upload_files/709/be3/536/709be3536c3f5933715ba5178a27d368.jpg)
Из чего состоит шаблон
В шаблоне на интеграцию (API) будут разделы:
Основная информация
Запрос/Ответ
Входные параметры
Проверки
Выходные параметры
Положительный ответ
Ответ с ошибками
Описание интеграции
Интеграции
Интеграция с сервисом №1
Почему именно такая структура?
Спокойствие, только спокойствие, сейчас все расскажу!
Вспомните, у каждого участника команды были вопросы, мотивирующие его прочитать документацию. От них и отталкиваемся, поэтому такое содержание.
Основная информация
В разделе можно найти ответы на вопросы:
Зачем нужна новая интеграция бизнесу?
Что пользователи получат в результате разработки?
Запрос/Ответ, Входные и выходные параметры
В этих разделах документа есть информация:
Что мне делать: параметры запроса-ответа?
Где найти тестовые запрос-ответ?
Как бы это все сломать: какие ошибки можно сделать?
Описание интеграции
Здесь есть ответы на вопросы:
В какие системы сходить за данными или передать?
С какими системами есть взаимодействие, чтобы проверить весь путь?
Как переиспользовать или доработать сервис, чтобы ничего не сломать?
Как применить шаблон на практике
Аналитическая задача - описать интеграцию, которая позволить добавить информацию о животном на сайте. Аналитик понимает, что нужен сервис для работы с данными о животных и метод, который создаст запись (прим. в статье не описано почему именно такой метод спроектирован, потому что статья направлена именно на шаблон описания).
В шаблоне есть:
Основная информация
Раздел содержит таблицу, которая позволяет понять, о чем будет документ, и найти все ссылки в одном месте.
Автор - ФИО, кто пишет или правит документ
Задача - ссылка на задачу (например, JIRA) или описание задачи
Бизнес постановка - описание какую пользу приносит эта задача пользователям
Связанные документы - документы или ссылки с описанием, что в них находится
![Основная информация Основная информация](https://habrastorage.org/getpro/habr/upload_files/02c/0d1/904/02c0d190450d3925e8719e97d5fa6fd4.png)
История изменений документа
Раздел содержит таблицу:
Версия - номер версии
Дата - дата в формате ДД.ММ.ГГГ
Автор - ФИО кто создал или изменил документ
Описание изменений - текстовое описание того, что вы добавили в документ.
![История изменений История изменений](https://habrastorage.org/getpro/habr/upload_files/0d9/dde/7ad/0d9dde7ad618aeb6f665ed3872f0b5eb.png)
Запрос/Ответ
Пример запроса и ответа для добавления информации о животном на сайте
![Примеры запроса и ответа Примеры запроса и ответа](https://habrastorage.org/getpro/habr/upload_files/9ab/9bd/54e/9ab9bd54e2b74980e7495378ac38f26a.png)
Входные параметры
Раздел содержит таблицу:
Параметр - название параметра на английском
Тип данных - указать тип данных параметра с ограничениями по длине если они есть
Обязательность - да/нет
Описание - понятное описание для чего используется параметр
Варианты значений - перечислить варианты значений с пояснениями, для чего они используются или привести пример одного из значений
![Входные параметры Входные параметры](https://habrastorage.org/getpro/habr/upload_files/f94/1b8/209/f941b820937ec19e9d32269be95dc939.png)
Проверки
Раздел содержит таблицу:
Параметр - название параметра на английском
Проверка - условие и результат проверки
![Проверки входных параметров Проверки входных параметров](https://habrastorage.org/getpro/habr/upload_files/87d/479/be5/87d479be5a4f0fedcdd8dcdd49d21bf0.png)
Выходные параметры
Положительный ответ
Параметры аналогичны входным
Ответ с ошибками
![Ответ с ошибками Ответ с ошибками](https://habrastorage.org/getpro/habr/upload_files/6d9/421/c31/6d9421c3104f5ed097adee9f66d5be81.png)
Описание интеграции
![Схема работы метода по добавлению записи о животном Схема работы метода по добавлению записи о животном](https://habrastorage.org/getpro/habr/upload_files/ffb/c29/fd5/ffbc29fd52e06445ffa86cd31deb2a03.png)
Для построения сервиса использовался инструмент plantuml. Работа с ним описана в статье https://habr.com/ru/post/661931/
Посмотреть реализованный сервис можно по ссылке https://petstore.swagger.io/#/pet/addPet. Для удобства описания были придуманы некоторые проверки и коды ошибок :)
Интеграции
В разделе описываются сервисы, которые вызываются из выше описанного метода. Формат описания также будет содержать запрос и ответ, входные и выходные параметры.
Например, если бы метод POST /pet пошел бы в следующую систему для сохранения информации о животном.
Вы получили шаблон технической документации на API . Скачать шаблон google docs можно по ссылке
Его можно адаптировать под потребности людей, которые читают ваши документы. Документ может быть удобен вам, но разработчик, тестировщик и другие ребятам из команды не найдут ответы на свои вопросы. Поэтому хорошей практикой будет систематический сбор обратной связи от вашей команды, а все ли им удобно и понятно в документе.
![](https://habrastorage.org/getpro/habr/upload_files/e6b/59e/a3d/e6b59ea3d9f6161c6e929a8183d17995.webp)
Возможно вам шаблон не подойдет, но вы всегда можете составить свой и поделиться им в комментариях.