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

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

Сегодня расскажу подробно про портал документации Alfa API — рабочий инструмент, с которым можно быстро разобраться в продуктах банка, понять, как они реализованы технически, и улучшить впечатления от работы с ними. 

Для меня это не просто сборник туториалов, это лицо банка.

Как мы создавали портал документации

GitHub как первый шаг

На старте разработки API мы гнались за эффективностью и скоростью, поэтому обратились к GitHub. Ставку сделали на гибкость и удобство платформы для совместной работы. Мы используем Markdown: с ним легче создавать и обновлять документацию, у разработчиков под рукой примеры кода, и они могут работать с файлами Swagger. Этот выбор казался идеальным в начале пути.

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

Переход к собственной платформе

Увидев минусы GitHub, мы загорелись создать свой портал для документации. Решение не было спонтанным, оно отвечало стратегии цифровой трансформации Альфы. Сейчас расскажу, какие запросы закрывала наша платформа.

Технологический суверенитет

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

Уход от рисков коробочных решений

Зависимость от сторонней разработки — потенциальная угроза для бизнеса. Это ограничения в доработках, возможная смена лицензирования, а иногда и прекращение поддержки продукта. С собственным порталом документации мы могли быстро адаптироваться к изменениям в бизнес-процессах и в технологической среде и забыть об ограничениях поставщиков.

Гибкость и удобство использования

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

UX-исследования и кастомизация

Мы придерживаемся правила, что продукт должен отвечать ожиданиям пользователей и даже превосходить их. Но полагаться на ощущения нельзя, нужно погружаться в мир пользовательских ожиданий.

Исследование конкурентов: взять лучшее 

Мы начали с анализа рынка и изучили, как технологические гиганты — Finastra, PayPal, Talkdesk, Plaid, Stripe и другие, создают и ведут API-документацию. Затем вдохновились их идеями и реализовали лучший функционал из найденного, например, прямое тестирование API из документации, гибкое версионирование, удобную фильтрацию.

Понять пользователя и создать ценность

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

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

Бенчмаркинг: на пути к совершенству

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

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

Чем интересна документация Alfa API

Структура навигации

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

Широкий формат для глубокого погружения

Комфорт чтения важен для восприятия информации, поэтому мы сделали редизайн вёрстки, представив документацию в широком формате, чтобы избежать такого эффекта:

Мы оптимально используем пространство экрана, улучшаем читаемость кода и описаний, чтобы просмотр был удовольствием, а не рутиной.

Навигация, которая думает о вас

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

Полнотекстовый поиск

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

Тегирование: каждая деталь важна

Мы внедрили систему тегирования для продуктов, сервисов и статей. Теги — это маяк в море контента. Тег «Новое» выделяет свежие публикации, а тег «Скоро в релизе» как предсказатель анонсирует функционал, который вот-вот будет на проде.

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

Человечность в технической документации

Документация не должна быть скучной. Мы запустили короткие видеоролики и видеоинструкции от разработчиков документации. С ними изучение API становится «человечным», интерактивным и понятным. 

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

Что в итоге

Успех нашего открытого API кроется в качественной документации. В статье я описал концепции, на которые мы опирались, и показал примеры, как реализован портал и поиск информации на нём. С ними вы тоже сможете создать удобную и понятную документацию.

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

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